Initial commit: Card Grader deployed to hippofam.com/cards

PWA card-grading app, deployed behind Nginx Proxy Manager on Unraid with basic auth. Includes CARD_GRADER_BASE_PATH support for running under a sub-path, and Docker/compose config for the Unraid deployment.
2026-08-22 09:22:41 -07:00 · 2026-08-22 09:22:41 -07:00 · c7bd71a3e1
commit c7bd71a3e1
19 changed files with 3618 additions and 0 deletions
--- a/static/app.js
+++ b/static/app.js
@ -0,0 +1,572 @@
+/* Card Grader — UI */
+
+const state = { settings: {}, modelGuide: {}, history: [] };
+
+const $ = (sel) => document.querySelector(sel);
+
+function esc(text) {
+  return String(text === null || text === undefined ? '' : text)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/* ------------------------------------------------------------------ api */
+
+// The path this app is mounted under (e.g. "/cards"), or "" at the domain
+// root — set server-side via a data attribute since a script has no other
+// reliable way to know where it was served from.
+const APP_BASE = document.documentElement.dataset.base || '';
+
+async function api(path, options = {}) {
+  const response = await fetch(APP_BASE + path, {
+    headers: { 'Content-Type': 'application/json' },
+    ...options,
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+  const text = await response.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch (_) { data = null; }
+  if (!response.ok) {
+    throw new Error((data && data.error) || `Request failed (${response.status})`);
+  }
+  return data;
+}
+
+function banner(message, isError = false) {
+  const node = $('#banner');
+  if (!message) { node.hidden = true; return; }
+  node.className = isError ? 'banner err' : 'banner';
+  node.textContent = message;
+  node.hidden = false;
+  if (!isError) setTimeout(() => { node.hidden = true; }, 3200);
+}
+
+/* ------------------------------------------------------------- file read */
+//
+// Read straight to a data URL at pick time, and only clear the input once
+// the bytes are safely in hand. Holding File objects and reading them later
+// looks equivalent and isn't: clearing input.value (which is what lets you
+// re-pick the same file) can detach the underlying blob in some browsers, so
+// a read attempted afterward fails with no useful reason. Reading now
+// sidesteps that, and the data URL doubles as the preview source.
+
+function bytesToBase64(bytes) {
+  // Chunked: fromCharCode.apply on a multi-megabyte array blows the stack.
+  let binary = '';
+  const chunk = 0x8000;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode.apply(null, bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+
+async function readOneImage(file) {
+  // Two independent read paths, because they fail independently. FileReader
+  // is the older API and is the one that trips over files a phone exposes
+  // through a cloud provider or a scoped-storage URI; file.arrayBuffer() is
+  // the modern path and frequently succeeds where it doesn't. Trying both
+  // turns a hard failure into a retry, and if both fail the real
+  // DOMException name gets reported rather than a guess at the cause.
+  const errors = [];
+  try {
+    const buffer = await file.arrayBuffer();
+    if (buffer && buffer.byteLength) {
+      const type = file.type || 'image/jpeg';
+      return `data:${type};base64,${bytesToBase64(new Uint8Array(buffer))}`;
+    }
+    errors.push('arrayBuffer returned nothing');
+  } catch (err) {
+    errors.push(`arrayBuffer: ${err && err.name ? err.name : err}`);
+  }
+
+  try {
+    return await new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => resolve(String(reader.result));
+      reader.onerror = () => reject(reader.error || new Error('unknown'));
+      reader.readAsDataURL(file);
+    });
+  } catch (err) {
+    errors.push(`FileReader: ${err && err.name ? err.name : err}`);
+  }
+
+  const detail = errors.join('; ');
+  const hint = /NotReadable|NotFound/i.test(detail)
+    ? ' The file may be stored in the cloud rather than on the device — open it once in your photo app so it downloads, then try again.'
+    : ' Try saving a copy of it first, then pick the copy.';
+  throw new Error(`Could not read "${file.name || 'that file'}" (${detail}).${hint}`);
+}
+
+async function readPickedImages(input, limit) {
+  const picked = Array.from(input.files || []).slice(0, Math.max(0, limit));
+  const out = [];
+  for (const file of picked) {
+    out.push({ name: file.name || 'upload', dataUrl: await readOneImage(file) });
+  }
+  input.value = '';
+  return out;
+}
+
+function pickedToPayload(items) {
+  return items.map((i) => ({ filename: i.name, image_base64: i.dataUrl.split(',')[1] }));
+}
+
+/* --------------------------------------------------------------- grading */
+
+const SEVERITY_PILL = {
+  none: 'pill-grade', minor: 'pill-marginal', moderate: 'pill-marginal',
+  major: 'pill-critical', cannot_assess: 'pill-raw',
+};
+const SEVERITY_LABEL = {
+  none: 'clean', minor: 'minor', moderate: 'moderate', major: 'major',
+  cannot_assess: "can't tell from photo",
+};
+
+const gradeState = { files: [], result: null, busy: false };
+
+function renderGradeBlock(g) {
+  if (!g) return '';
+  const m = g.edge_measurements || null;
+  let measuredLine = '';
+  if (m && m.reliable === false) {
+    measuredLine = `not measurable — ${m.reason || "this card's finish"}`;
+  } else if (m && m.edges) {
+    measuredLine = ['top', 'right', 'bottom', 'left']
+      .filter((s) => m.edges[s])
+      .map((s) => `${s} ${m.edges[s].percent.toFixed(0)}%`).join(' · ');
+  }
+
+  const cm = g.centering_measurement || null;
+  const centeringLine = cm
+    ? `measured — left/right ${cm.horizontal_label} · top/bottom ${cm.vertical_label}` : '';
+
+  const rows = ['centering', 'corners', 'edges', 'surface'].map((key) => {
+    const cat = (g.categories || {})[key] || {};
+    const sev = cat.severity || 'cannot_assess';
+    let extra = '';
+    if (key === 'edges' && measuredLine) {
+      extra = `<div class="hint">measured whitening — ${esc(measuredLine)}</div>`;
+    } else if (key === 'centering' && centeringLine) {
+      extra = `<div class="hint">${esc(centeringLine)}</div>`;
+    }
+    return `<tr>
+        <td style="text-transform:capitalize">${key}</td>
+        <td><span class="pill ${SEVERITY_PILL[sev]}">${esc(SEVERITY_LABEL[sev])}</span></td>
+        <td class="cardcell-meta">${esc(cat.observation || '')}${extra}</td>
+      </tr>`;
+  }).join('');
+
+  return `
+    <div class="note">A photo can't show surface scratches, print lines, or light edge wear the
+      way a grader's raking light does — and a seller's listing photo is often lit to hide them.
+      Treat this as a rough screen, not a prediction of what it comes back as.</div>
+    <div style="margin:14px 0">${renderSlab(g)}</div>
+    <div class="table-scroll"><table class="grid"><tbody>${rows}</tbody></table></div>
+    ${(g.limitations || []).length ? `<div style="margin-top:10px"><strong>Couldn't check:</strong>
+      <ul>${g.limitations.map((l) => `<li>${esc(l)}</li>`).join('')}</ul></div>` : ''}
+    ${g.note ? `<p class="cardcell-meta">${esc(g.note)}</p>` : ''}`;
+}
+
+const GRADE_WORD = {
+  10: 'Gem Mint', 9: 'Mint', 8: 'NM-MT', 7: 'Near Mint', 6: 'EX-MT',
+  5: 'Excellent', 4: 'VG-EX', 3: 'Very Good', 2: 'Good', 1: 'Poor',
+};
+const TYPE_LABEL = {
+  pokemon: 'Pokémon', sports: 'Sports', other_tcg: 'TCG', other: 'Card',
+};
+
+function slabClass(grade) {
+  if (grade === null || grade === undefined) return 'slab-low';
+  if (grade >= 10) return 'slab-10';
+  if (grade === 9) return 'slab-9';
+  if (grade >= 7) return 'slab-8';
+  if (grade >= 5) return 'slab-6';
+  return 'slab-low';
+}
+
+function renderSlab(g, opts = {}) {
+  const grade = g.estimated_grade;
+  const range = (g.grade_low !== null && g.grade_high !== null && g.grade_low !== g.grade_high)
+    ? `realistically ${g.grade_low}–${g.grade_high}` : '';
+  const title = opts.title || g.card_note || 'Card';
+  const bits = [range, `${g.confidence || ''} confidence`].filter(Boolean).join(' · ');
+  return `
+    <div class="slab ${slabClass(grade)}">
+      <div class="slab-main">
+        ${g.card_type ? `<div><span class="card-type-tag">${esc(TYPE_LABEL[g.card_type] || 'Card')}</span></div>` : ''}
+        <div class="slab-title">${esc(title)}</div>
+        <div class="slab-sub">${esc(bits)}</div>
+      </div>
+      <div class="slab-grade">
+        <span class="n">${grade === null || grade === undefined ? '—' : grade}</span>
+        <span class="word">${esc(GRADE_WORD[grade] || 'estimate')}</span>
+      </div>
+    </div>`;
+}
+
+function renderGradeReview() {
+  const el = $('#grade-review');
+  if (!gradeState.files.length && !gradeState.result) { el.innerHTML = ''; return; }
+
+  if (!gradeState.result) {
+    el.innerHTML = `
+      <div class="panel" style="margin-top:14px;background:var(--plane)">
+        <div class="panel-head">
+          <h2>${gradeState.files.length} photo(s) ready</h2>
+          <span class="hint">more angles = a tighter estimate</span>
+        </div>
+        <div style="display:flex;gap:12px;align-items:center;flex-wrap:wrap">
+          ${gradeState.files.map((f) =>
+            `<img src="${f.dataUrl}" alt="" style="height:110px;border-radius:8px">`).join('')}
+          <div style="display:flex;flex-direction:column;gap:8px">
+            <button class="btn btn-quiet btn-sm" id="grade-add-more">+ Add another photo</button>
+            <button class="btn" id="grade-run"${gradeState.busy ? ' disabled' : ''}>
+              ${gradeState.busy ? 'Grading…' : 'Estimate the grade'}</button>
+            <button class="btn btn-quiet btn-sm" id="grade-cancel">Cancel</button>
+          </div>
+        </div>
+      </div>`;
+    return;
+  }
+
+  const g = gradeState.result.grade;
+  const cost = gradeState.result.grade.estimated_cost;
+  el.innerHTML = `
+    <div class="panel" style="margin-top:14px;background:var(--plane)">
+      <div class="panel-head">
+        <h2>Grade estimate</h2>
+        <span class="hint">${cost ? `about $${cost.toFixed(3)}` : ''}</span>
+      </div>
+      ${renderGradeBlock(g)}
+      <div class="drawer-actions">
+        <button class="btn btn-quiet" id="grade-discard">Done</button>
+      </div>
+    </div>`;
+}
+
+async function runGrade() {
+  gradeState.busy = true;
+  renderGradeReview();
+  const status = $('#grade-status');
+  status.hidden = false;
+  status.textContent = `Reading ${gradeState.files.length} photo(s)… this takes a few seconds and costs a few cents.`;
+  try {
+    const body = {
+      images: pickedToPayload(gradeState.files),
+      label: ($('#grade-label').value || '').trim() || null,
+    };
+    const key = myApiKey();
+    if (key) body.api_key = key;
+    gradeState.result = await api('/api/grade', { method: 'POST', body });
+    status.hidden = true;
+    $('#grade-label').value = '';
+    loadHistory().catch(() => {});
+  } catch (err) {
+    status.textContent = `Grading failed: ${err.message}`;
+  } finally {
+    gradeState.busy = false;
+    renderGradeReview();
+  }
+}
+
+function resetGradeState() {
+  gradeState.files = [];
+  gradeState.result = null;
+  gradeState.busy = false;
+  $('#grade-status').hidden = true;
+  renderGradeReview();
+}
+
+$('#btn-grade').addEventListener('click', () => {
+  resetGradeState();
+  $('#grade-file').click();
+});
+$('#grade-file').addEventListener('change', async (e) => {
+  try {
+    const picked = await readPickedImages(e.target, 6 - gradeState.files.length);
+    if (!picked.length) return;
+    gradeState.files.push(...picked);
+    renderGradeReview();
+  } catch (err) {
+    $('#grade-status').hidden = false;
+    $('#grade-status').textContent = err.message;
+  }
+});
+$('#grade-review').addEventListener('click', (e) => {
+  if (e.target.closest('#grade-add-more')) { $('#grade-file').click(); return; }
+  if (e.target.closest('#grade-cancel') || e.target.closest('#grade-discard')) {
+    resetGradeState(); return;
+  }
+  if (e.target.closest('#grade-run')) {
+    if (!gradeState.busy) runGrade();
+  }
+});
+
+/* --------------------------------------------------------------- history */
+
+function gradePillClass(grade) {
+  if (grade === null || grade === undefined) return 'pill-raw';
+  if (grade >= 8) return 'pill-grade';
+  if (grade >= 5) return 'pill-marginal';
+  return 'pill-critical';
+}
+
+function fmtWhen(iso) {
+  if (!iso) return '';
+  return String(iso).replace('T', ' ').slice(0, 16);
+}
+
+async function loadHistory() {
+  const data = await api('/api/history');
+  state.history = data.grades;
+  renderHistory();
+}
+
+function renderHistory() {
+  const rows = state.history;
+  $('#history-count').textContent = rows.length ? `${rows.length} graded` : '';
+  $('#history-empty').hidden = rows.length > 0;
+  $('#history-body').innerHTML = rows.map((g) => `
+    <tr data-history-row="${g.id}">
+      <td>
+        <div class="cardcell">
+          ${g.thumbnail ? `<img src="${g.thumbnail}" alt="">` : '<span class="thumb-blank"></span>'}
+          <div>
+            <div class="cardcell-name">${esc(g.label || g.card_note || 'Untitled card')}</div>
+            <div class="cardcell-meta">${g.card_type ? `${esc(TYPE_LABEL[g.card_type] || 'Card')} · ` : ''}${g.image_count || 1} photo(s)</div>
+          </div>
+        </div>
+      </td>
+      <td><span class="pill ${gradePillClass(g.estimated_grade)}">${
+        g.estimated_grade === null ? 'n/a' : `PSA ${g.estimated_grade}`}</span></td>
+      <td class="cardcell-meta">${esc(g.confidence || '')}</td>
+      <td class="cardcell-meta">${esc(fmtWhen(g.created_at))}</td>
+      <td class="num"><button class="btn btn-quiet btn-sm" data-history-delete="${g.id}">Delete</button></td>
+    </tr>`).join('');
+}
+
+function renderEntryModal(g) {
+  $('#entry-modal').innerHTML = `
+    <div class="panel-head">
+      <h2>${esc(g.label || g.card_note || 'Untitled card')}</h2>
+      <button class="close" id="entry-close">&times;</button>
+    </div>
+    <div class="cardcell-meta" style="margin-bottom:10px">${esc(fmtWhen(g.created_at))} ·
+      ${g.usage && g.usage.model ? esc(g.usage.model) : ''}</div>
+    ${renderGradeBlock(g)}
+    <div class="drawer-actions">
+      <input class="input" id="entry-label" placeholder="Rename this card…" value="${esc(g.label || '')}" style="flex:1 1 200px">
+      <button class="btn btn-quiet btn-sm" id="entry-save-label">Save name</button>
+      <span class="spacer"></span>
+      <button class="btn btn-danger btn-sm" data-history-delete="${g.id}">Delete</button>
+    </div>`;
+  $('#entry-modal').hidden = false;
+  $('#entry-scrim').hidden = false;
+}
+
+function closeEntryModal() {
+  $('#entry-modal').hidden = true;
+  $('#entry-scrim').hidden = true;
+}
+
+$('#history-body').addEventListener('click', async (e) => {
+  const del = e.target.closest('[data-history-delete]');
+  if (del) {
+    e.stopPropagation();
+    await api(`/api/history/${del.dataset.historyDelete}`, { method: 'DELETE' });
+    await loadHistory();
+    return;
+  }
+  const row = e.target.closest('[data-history-row]');
+  if (row) {
+    try {
+      const data = await api(`/api/history/${row.dataset.historyRow}`);
+      renderEntryModal(data.grade);
+    } catch (err) {
+      banner(err.message, true);
+    }
+  }
+});
+
+$('#entry-modal').addEventListener('click', async (e) => {
+  if (e.target.closest('#entry-close')) return closeEntryModal();
+  const del = e.target.closest('[data-history-delete]');
+  if (del) {
+    await api(`/api/history/${del.dataset.historyDelete}`, { method: 'DELETE' });
+    closeEntryModal();
+    await loadHistory();
+    return;
+  }
+  if (e.target.closest('#entry-save-label')) {
+    const id = $('#entry-modal').querySelector('[data-history-delete]').dataset.historyDelete;
+    const label = $('#entry-label').value.trim();
+    await api(`/api/history/${id}`, { method: 'PATCH', body: { label } });
+    closeEntryModal();
+    await loadHistory();
+    banner('Renamed.');
+  }
+});
+$('#entry-scrim').addEventListener('click', closeEntryModal);
+
+/* -------------------------------------------------------------- settings */
+
+async function openSettings() {
+  const s = state.settings;
+  try { state.modelGuide = await api('/api/vision-models'); } catch (_) { state.modelGuide = {}; }
+
+  const modelOptions = Object.entries(state.modelGuide).map(([id, info]) =>
+    `<option value="${id}" ${s.vision_model === id ? 'selected' : ''}>
+      ${esc(info.label)} — ~$${info.per_grade.toFixed(3)}/grade</option>`).join('');
+
+  const locked = s.settings_locked;
+
+  $('#settings-modal').innerHTML = `
+    <div class="panel-head">
+      <h2>Settings</h2>
+      <button class="close" id="settings-close">&times;</button>
+    </div>
+
+    <div class="section">
+      <h3>Your API key</h3>
+      <div class="fields">
+        <div class="field wide">
+          <label>Anthropic API key (this browser only)</label>
+          <input class="input" id="set-my-key" type="password" value="${esc(myApiKey() || '')}"
+                 placeholder="sk-ant-...">
+          <span class="suffix">Stored only in this browser and sent with your own grading
+            requests — never saved on the server. Get one at console.anthropic.com.
+            ${s.server_key_configured
+              ? 'This server already has a key set up, so you can leave this blank and use that instead — but then the owner pays for your grades.'
+              : 'This server has no key of its own, so you need one here to grade anything.'}</span>
+        </div>
+      </div>
+    </div>
+
+    <div class="section">
+      <h3>Server settings${locked ? ' <span class="pill pill-raw">locked</span>' : ''}</h3>
+      ${locked ? `<div class="note">This server is shared, so its settings are read-only.
+        Use your own key above.</div>` : `
+      <div class="fields">
+        <div class="field wide">
+          <label>Server API key (used when a visitor has none)</label>
+          <input class="input" id="set-api-key" type="password"
+                 placeholder="${s.server_key_configured ? '•••••••• already set — type to replace' : 'sk-ant-...'}">
+          <span class="suffix">Never sent back to the browser once saved. Leave blank to keep
+            the current one.</span>
+        </div>
+        <div class="field wide">
+          <label>Vision model</label>
+          <select id="set-model">${modelOptions}</select>
+          <span class="suffix">Sonnet 5 is the default for a tested reason — run head-to-head
+            against Haiku on the same cards, Haiku misread a PSA centering tolerance and landed
+            three grades off. Drop to Haiku only if cost matters more than accuracy to you.</span>
+        </div>
+      </div>`}
+    </div>
+
+    <div class="drawer-actions">
+      <button class="btn" id="settings-save">Save</button>
+    </div>`;
+  $('#settings-modal').hidden = false;
+  $('#modal-scrim').hidden = false;
+}
+
+/* A personal key lives in localStorage, never on the server — that's what
+   lets someone use a shared instance without spending the owner's credits. */
+function myApiKey() {
+  try { return localStorage.getItem('cardgrader_api_key') || ''; } catch (_) { return ''; }
+}
+function setMyApiKey(value) {
+  try {
+    if (value) localStorage.setItem('cardgrader_api_key', value);
+    else localStorage.removeItem('cardgrader_api_key');
+  } catch (_) { /* private browsing — the field just won't persist */ }
+}
+
+function closeSettings() {
+  $('#settings-modal').hidden = true;
+  $('#modal-scrim').hidden = true;
+}
+
+async function saveSettings() {
+  setMyApiKey($('#set-my-key').value.trim());
+
+  // Only push server settings when this instance allows it, and only send a
+  // key when one was actually typed — an empty box means "leave it alone",
+  // not "erase it".
+  const serverKeyField = $('#set-api-key');
+  if (serverKeyField) {
+    const payload = { vision_model: $('#set-model').value };
+    const typed = serverKeyField.value.trim();
+    if (typed) payload.anthropic_api_key = typed;
+    state.settings = await api('/api/settings', { method: 'POST', body: payload });
+  }
+  closeSettings();
+  updateModelCostHint();
+  banner('Settings saved.');
+}
+
+function updateModelCostHint() {
+  const info = state.modelGuide[state.settings.vision_model];
+  $('#model-cost-hint').textContent = info ? `~$${info.per_grade.toFixed(3)} per grade (${info.label})` : '';
+}
+
+$('#btn-settings').addEventListener('click', () => openSettings().catch((err) => banner(err.message, true)));
+$('#settings-modal').addEventListener('click', (e) => {
+  if (e.target.closest('#settings-close')) return closeSettings();
+  if (e.target.closest('#settings-save')) saveSettings().catch((err) => banner(err.message, true));
+});
+$('#modal-scrim').addEventListener('click', closeSettings);
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape') { closeSettings(); closeEntryModal(); }
+});
+
+/* ---------------------------------------------------------------- load */
+
+async function load() {
+  state.settings = await api('/api/settings');
+  try { state.modelGuide = await api('/api/vision-models'); } catch (_) { state.modelGuide = {}; }
+  updateModelCostHint();
+  await loadHistory();
+  if (!state.settings.server_key_configured && !myApiKey()) {
+    banner('Add your Anthropic API key in Settings before grading a card.');
+  }
+}
+
+load().catch((err) => banner(`Could not load: ${err.message}`, true));
+
+/* ------------------------------------------------------------------ pwa */
+//
+// Service workers only run in a secure context: https, or localhost. Over a
+// plain LAN address (http://192.168.x.x) registration silently fails and the
+// app stays a normal web page — which is exactly why the README pushes you
+// through a tunnel rather than just handing friends your LAN IP.
+
+if ('serviceWorker' in navigator) {
+  window.addEventListener('load', () => {
+    navigator.serviceWorker.register(APP_BASE + '/sw.js').catch(() => {
+      /* Not fatal — the app works fine uninstalled. */
+    });
+  });
+}
+
+// Android/Chrome fires this instead of showing its own prompt, so the offer
+// has to be surfaced deliberately. iOS never fires it: Safari has no
+// programmatic install, only the manual Share > Add to Home Screen, so the
+// hint below covers that case instead of pretending a button exists.
+let deferredInstall = null;
+window.addEventListener('beforeinstallprompt', (e) => {
+  e.preventDefault();
+  deferredInstall = e;
+  const btn = $('#btn-install');
+  if (btn) btn.hidden = false;
+});
+
+document.addEventListener('click', async (e) => {
+  if (!e.target.closest('#btn-install')) return;
+  if (!deferredInstall) return;
+  deferredInstall.prompt();
+  await deferredInstall.userChoice;
+  deferredInstall = null;
+  $('#btn-install').hidden = true;
+});
--- a/static/icon-180.png
+++ b/static/icon-180.png
--- a/static/icon-192.png
+++ b/static/icon-192.png
--- a/static/icon-512-maskable.png
+++ b/static/icon-512-maskable.png
--- a/static/icon-512.png
+++ b/static/icon-512.png
--- a/static/icon.svg
+++ b/static/icon.svg
@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128">
+  <rect width="128" height="128" rx="24" fill="#16224a"/>
+  <rect x="34" y="24" width="60" height="80" rx="8" fill="#2f6fd0" stroke="#35c6a8" stroke-width="3"/>
+  <path d="M48 66 L60 78 L84 50" fill="none" stroke="#ffffff" stroke-width="7"
+        stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
--- a/static/index.html
+++ b/static/index.html
@ -0,0 +1,90 @@
+<!doctype html>
+<html lang="en" data-base="__BASE__">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Card Grader</title>
+<link rel="manifest" href="__BASE__/static/manifest.json">
+<link rel="icon" href="__BASE__/static/icon.svg">
+<meta name="theme-color" content="#16224a">
+<!-- iOS ignores the web app manifest for install behaviour and needs its own
+     meta tags. Without these, "Add to Home Screen" on an iPhone produces a
+     bookmark that opens in Safari with the address bar showing, rather than
+     something that looks and behaves like an installed app. -->
+<meta name="apple-mobile-web-app-capable" content="yes">
+<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+<meta name="apple-mobile-web-app-title" content="Card Grader">
+<link rel="apple-touch-icon" href="__BASE__/static/icon-180.png">
+<link rel="stylesheet" href="__BASE__/static/style.css">
+</head>
+<body>
+
+<header class="topbar">
+  <div class="brand">
+    <span class="brand-mark"></span>
+    <h1>Card Grader</h1>
+  </div>
+  <div class="topbar-actions">
+    <button id="btn-install" class="btn" hidden>Install app</button>
+    <button id="btn-settings" class="btn btn-quiet">Settings</button>
+  </div>
+</header>
+
+<div id="banner" class="banner" hidden></div>
+
+<main>
+
+  <!-- ------------------------------------------------------------- grade -->
+  <section class="panel">
+    <div class="panel-head">
+      <h2>Grade a card</h2>
+      <span class="hint" id="model-cost-hint"></span>
+    </div>
+    <div class="note">Front straight-on is the minimum. Adding the back lets it judge
+      back centering, and it can only tell a print line from a crease — about five PSA
+      grades apart — if it can check both sides.</div>
+    <div style="display:flex;gap:10px;flex-wrap:wrap;margin-top:12px">
+      <button id="btn-grade" class="btn">Choose photo(s)…</button>
+      <input id="grade-label" class="input" placeholder="Card name (optional, for your history)" style="flex:1 1 220px">
+    </div>
+    <input id="grade-file" type="file" accept="image/*" multiple hidden>
+    <div id="grade-status" class="search-status" hidden></div>
+    <div id="grade-review"></div>
+  </section>
+
+  <!-- ----------------------------------------------------------- history -->
+  <section class="panel">
+    <div class="panel-head">
+      <h2>History</h2>
+      <span class="hint" id="history-count"></span>
+    </div>
+    <div class="table-scroll">
+      <table class="grid" id="history-table">
+        <thead>
+          <tr>
+            <th class="col-card">Card</th>
+            <th>Grade</th>
+            <th>Confidence</th>
+            <th>When</th>
+            <th></th>
+          </tr>
+        </thead>
+        <tbody id="history-body"></tbody>
+      </table>
+    </div>
+    <p id="history-empty" class="empty" hidden>Nothing graded yet.</p>
+  </section>
+
+</main>
+
+<!-- ----------------------------------------------------------- settings -->
+<div id="modal-scrim" class="scrim" hidden></div>
+<div id="settings-modal" class="modal" hidden role="dialog" aria-label="Settings"></div>
+
+<!-- ------------------------------------------------------- history entry -->
+<div id="entry-scrim" class="scrim" hidden></div>
+<div id="entry-modal" class="modal" hidden role="dialog" aria-label="Grade detail"></div>
+
+<script src="__BASE__/static/app.js"></script>
+</body>
+</html>
--- a/static/manifest.json
+++ b/static/manifest.json
@ -0,0 +1,17 @@
+{
+  "name": "Card Grader",
+  "short_name": "Card Grader",
+  "description": "Estimate a trading card's PSA grade from photos.",
+  "start_url": "__BASE__/",
+  "scope": "__BASE__/",
+  "display": "standalone",
+  "orientation": "portrait",
+  "background_color": "#0a0f1c",
+  "theme_color": "#16224a",
+  "icons": [
+    { "src": "__BASE__/static/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
+    { "src": "__BASE__/static/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
+    { "src": "__BASE__/static/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" },
+    { "src": "__BASE__/static/icon.svg", "sizes": "any", "type": "image/svg+xml", "purpose": "any" }
+  ]
+}
--- a/static/style.css
+++ b/static/style.css
@ -0,0 +1,367 @@
+/* Card Grader — neutral theme, card-type agnostic (Pokemon, sports, TCG).
+
+   Colour discipline:
+   - Grade severities ride a lightness ladder (none -> minor -> moderate ->
+     major), so the table still reads as escalating severity in greyscale.
+   - Red is reserved for "you should distrust this number" (unmeasurable
+     edges, a low grade) — never decorative.
+   - Light and dark are separately selected steps, not an inverted flip. */
+
+:root {
+  color-scheme: light;
+  --surface-1:   #ffffff;
+  --plane:       #eef2fa;
+  --ink:         #101828;
+  --ink-2:       #475467;
+  --muted:       #7a8699;
+  --hairline:    #dfe6f2;
+  --rule:        #c3cede;
+  --accent:      #2f6fd0;
+  --accent-2:    #35c6a8;   /* mark accent — fills only, never text on light */
+  --accent-soft: #dbe8fc;
+  --good:        #10a44a;
+  --good-text:   #077a35;
+  --warning:     #e8912f;
+  --critical:    #d63a3a;
+  --header-1:    #16224a;
+  --header-2:    #24407e;
+  --header-3:    #2f6fd0;
+
+  --ring:        rgba(16, 24, 40, .10);
+  --shadow:      0 1px 2px rgba(16,24,40,.06), 0 8px 24px rgba(16,24,40,.10);
+  --radius:      13px;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:where(:not([data-theme="light"])) {
+    color-scheme: dark;
+    --surface-1:   #141c2f;
+    --plane:       #0a0f1c;
+    --ink:         #ffffff;
+    --ink-2:       #b6c2d6;
+    --muted:       #8592a8;
+    --hairline:    #253150;
+    --rule:        #35446a;
+    --accent:      #4b8ee8;
+    --accent-2:    #45dcbb;
+    --accent-soft: #1d3a66;
+    --good:        #22c55e;
+    --good-text:   #34d36a;
+    --warning:     #ffa64d;
+    --critical:    #ef5350;
+    --header-1:    #0d1530;
+    --header-2:    #17285a;
+    --header-3:    #1f4488;
+
+    --ring:        rgba(255,255,255,.12);
+    --shadow:      0 1px 2px rgba(0,0,0,.45), 0 8px 28px rgba(0,0,0,.55);
+  }
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  background-color: var(--plane);
+  background-image: radial-gradient(circle at 1px 1px, var(--hairline) 1px, transparent 0);
+  background-size: 22px 22px;
+  color: var(--ink);
+  font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+h1, h2, h3 { margin: 0; font-weight: 600; }
+h1 { font-size: 16px; letter-spacing: -.01em; }
+h2 { font-size: 15px; }
+h3 { font-size: 13px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); font-weight: 600; }
+
+main {
+  max-width: 900px;
+  margin: 0 auto;
+  padding: 20px 24px 80px;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+/* ------------------------------------------------------------- topbar */
+
+.topbar {
+  position: sticky; top: 0; z-index: 20;
+  display: flex; align-items: center; justify-content: space-between;
+  gap: 16px; flex-wrap: wrap;
+  padding: 13px 24px;
+  background: linear-gradient(100deg, var(--header-1), var(--header-2) 55%, var(--header-3));
+  color: #fff;
+  /* Holo-foil edge: the rainbow sweep you get tilting a refractor. Purely
+     decorative and it encodes nothing, so it's free to be vivid here where
+     no number lives. */
+  border-bottom: 3px solid transparent;
+  border-image: linear-gradient(90deg,
+    #ff5f8f, #ffb347, #ffe66d, #35c6a8, #4b8ee8, #a97bff, #ff5f8f) 1;
+}
+.topbar h1 { color: #fff; letter-spacing: .01em; }
+
+.topbar .btn {
+  background: var(--accent-2); color: #06231d;
+  border-color: transparent; font-weight: 600;
+}
+.topbar .btn:hover { filter: brightness(1.06); }
+.topbar .btn-quiet {
+  background: rgba(255,255,255,.14); color: #fff;
+  border-color: rgba(255,255,255,.38); font-weight: 500;
+}
+.topbar .btn-quiet:hover { background: rgba(255,255,255,.26); filter: none; }
+
+.brand { display: flex; align-items: center; gap: 11px; }
+
+/* Brand mark: a graded slab, drawn in plain CSS. A rounded card outline with
+   a corner clipped and a check — "this one's been looked at" — rather than
+   any single game's iconography, since this grades anything PSA does. */
+.brand-mark {
+  position: relative; flex: none;
+  width: 26px; height: 26px; border-radius: 6px;
+  background: linear-gradient(160deg, var(--accent-2), var(--accent));
+  box-shadow: inset 0 0 0 1.5px rgba(255,255,255,.4), 0 1px 4px rgba(0,0,0,.35);
+}
+.brand-mark::after {
+  content: ''; position: absolute; left: 6px; top: 6px;
+  width: 8px; height: 5px;
+  border-left: 2px solid #06231d; border-bottom: 2px solid #06231d;
+  transform: rotate(-45deg);
+}
+
+.topbar-actions { display: flex; gap: 8px; flex-wrap: wrap; }
+
+/* ------------------------------------------------------------ controls */
+
+.btn {
+  font: inherit; font-weight: 500; font-size: 14px;
+  padding: 7px 14px; border-radius: 8px; cursor: pointer;
+  background: var(--accent); color: #fff;
+  border: 1px solid transparent;
+  text-decoration: none; display: inline-block; line-height: 1.4;
+  white-space: nowrap;
+}
+.btn:hover { filter: brightness(1.07); }
+.btn:active { transform: translateY(.5px); }
+.btn[disabled] { opacity: .5; cursor: default; filter: none; }
+
+.btn-quiet {
+  background: var(--surface-1); color: var(--ink);
+  border-color: var(--rule);
+}
+.btn-quiet:hover { background: var(--plane); filter: none; }
+
+.btn-danger { background: transparent; color: var(--critical); border-color: var(--critical); }
+.btn-danger:hover { background: var(--critical); color: #fff; filter: none; }
+
+.btn-sm { padding: 4px 10px; font-size: 13px; }
+
+.input, select, textarea {
+  font: inherit; font-size: 14px;
+  padding: 7px 10px;
+  border: 1px solid var(--rule);
+  border-radius: 8px;
+  background: var(--surface-1);
+  color: var(--ink);
+  width: 100%;
+}
+.input:focus, select:focus, textarea:focus {
+  outline: 2px solid var(--accent); outline-offset: -1px; border-color: transparent;
+}
+textarea { resize: vertical; min-height: 60px; }
+
+/* --------------------------------------------------------------- tiles */
+
+.tile-value { font-size: 25px; font-weight: 700; letter-spacing: -.02em; }
+.tile-sub { font-size: 12px; color: var(--ink-2); margin-top: 4px; }
+.pos { color: var(--good-text); }
+.neg { color: var(--critical); }
+
+/* -------------------------------------------------------------- panels */
+
+.panel {
+  background: var(--surface-1);
+  border: 1px solid var(--hairline);
+  border-radius: var(--radius);
+  padding: 16px 18px 18px;
+  box-shadow: 0 1px 2px rgba(16,24,40,.04);
+}
+
+.panel-head {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: 12px; flex-wrap: wrap; margin-bottom: 12px;
+}
+.hint { font-size: 13px; color: var(--muted); }
+.search-status { margin-top: 10px; font-size: 13px; color: var(--ink-2); }
+
+/* --------------------------------------------------------------- table */
+
+.table-scroll { overflow-x: auto; }
+.grid { width: 100%; border-collapse: collapse; font-size: 14px; }
+.grid th {
+  text-align: left; font-size: 11.5px; font-weight: 600;
+  text-transform: uppercase; letter-spacing: .05em; color: var(--muted);
+  padding: 8px 10px; border-bottom: 1px solid var(--rule); white-space: nowrap;
+}
+.grid td {
+  padding: 9px 10px; border-bottom: 1px solid var(--hairline);
+  vertical-align: middle;
+}
+.grid tbody tr:hover { background: var(--accent-soft); }
+.num { text-align: right; font-variant-numeric: tabular-nums; }
+
+.cardcell { display: flex; align-items: center; gap: 10px; }
+.cardcell img, .cardcell .thumb-blank {
+  width: 40px; height: 56px; object-fit: cover;
+  border-radius: 4px; background: var(--plane); flex: none;
+}
+.thumb-blank {
+  display: inline-block;
+  border: 1px dashed var(--rule);
+  background:
+    repeating-linear-gradient(135deg, transparent 0 5px, var(--hairline) 5px 6px),
+    var(--plane);
+}
+.cardcell-name { font-weight: 600; line-height: 1.25; }
+.cardcell-meta { font-size: 12px; color: var(--muted); }
+.dash { color: var(--muted); }
+
+/* --------------------------------------------------------------- pills */
+
+.pill {
+  display: inline-flex; align-items: center; gap: 6px;
+  font-size: 12px; font-weight: 600;
+  padding: 3.5px 10px; border-radius: 99px;
+  border: 1px solid var(--rule); color: var(--ink-2);
+  white-space: nowrap;
+}
+.pill-grade    { border-color: var(--good); color: var(--good-text);
+                 background: color-mix(in srgb, var(--good) 12%, transparent); }
+.pill-marginal { border-color: var(--warning);
+                 background: color-mix(in srgb, var(--warning) 14%, transparent); }
+.pill-raw      { border-color: var(--rule); color: var(--muted); }
+.pill-critical { border-color: var(--critical); color: var(--critical);
+                 background: color-mix(in srgb, var(--critical) 12%, transparent); }
+
+.empty { text-align: center; color: var(--muted); padding: 28px 0 8px; font-size: 14px; }
+
+/* -------------------------------------------------------------- modal */
+
+.scrim {
+  position: fixed; inset: 0; z-index: 30;
+  background: rgba(11,11,11,.32);
+}
+.modal {
+  position: fixed; z-index: 40;
+  top: 50%; left: 50%; transform: translate(-50%, -50%);
+  width: min(560px, calc(100vw - 32px));
+  max-height: min(86vh, 900px); overflow-y: auto;
+  background: var(--surface-1);
+  border: 1px solid var(--hairline);
+  border-radius: 14px;
+  box-shadow: var(--shadow);
+  padding: 20px 22px;
+}
+.close {
+  background: none; border: none; cursor: pointer; font-size: 22px;
+  color: var(--muted); line-height: 1; padding: 0 4px;
+}
+.close:hover { color: var(--ink); }
+
+.section { margin-bottom: 20px; }
+.section > h3 { margin-bottom: 10px; }
+.fields { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+.field { display: flex; flex-direction: column; gap: 4px; }
+.field.wide { grid-column: 1 / -1; }
+.field label { font-size: 12px; color: var(--ink-2); }
+.suffix { display: block; font-size: 11.5px; line-height: 1.45; color: var(--muted); }
+
+.drawer-actions {
+  display: flex; gap: 8px; flex-wrap: wrap;
+  padding-top: 14px; border-top: 1px solid var(--hairline);
+}
+.spacer { flex: 1; }
+
+.note {
+  font-size: 12.5px; color: var(--ink-2);
+  background: var(--plane); border: 1px solid var(--hairline);
+  border-left: 3px solid var(--warning);
+  border-radius: 6px; padding: 9px 11px; margin-top: 10px;
+}
+.note-flag {
+  border-left-color: var(--critical);
+  color: var(--critical);
+  margin-top: 0; margin-bottom: 12px;
+}
+
+/* -------------------------------------------------------------- banner */
+
+.banner {
+  position: sticky; top: 57px; z-index: 15;
+  padding: 10px 24px; font-size: 13.5px;
+  background: var(--accent-soft); color: var(--ink);
+  border-bottom: 1px solid var(--hairline);
+}
+.banner.err { background: var(--critical); color: #fff; }
+.banner ul { margin: 4px 0 0; padding-left: 18px; }
+
+/* ---------------------------------------------------------- grade slab */
+/* Styled after the label on a graded slab, because that's the thing this
+   whole app is estimating — it makes the number read as a verdict rather
+   than as one more statistic on the page. */
+
+.slab {
+  display: flex; align-items: stretch; gap: 0;
+  border-radius: 10px; overflow: hidden;
+  border: 1px solid var(--rule);
+  background: var(--surface-1);
+  box-shadow: var(--shadow);
+  max-width: 420px;
+}
+.slab-main {
+  flex: 1; padding: 12px 14px;
+  display: flex; flex-direction: column; justify-content: center; gap: 2px;
+}
+.slab-title { font-size: 13px; font-weight: 700; line-height: 1.25; }
+.slab-sub { font-size: 11.5px; color: var(--muted); }
+.slab-grade {
+  flex: none; width: 104px;
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  padding: 10px 8px; color: #fff; text-align: center;
+  background: linear-gradient(150deg, var(--header-2), var(--header-3));
+}
+.slab-grade .n { font-size: 34px; font-weight: 800; line-height: 1; letter-spacing: -.02em; }
+.slab-grade .word { font-size: 9.5px; font-weight: 700; letter-spacing: .1em; text-transform: uppercase; opacity: .85; margin-top: 3px; }
+
+/* Grade bands. Green for a card worth submitting, amber mid, red low —
+   the same red reserved elsewhere for "distrust this", used here because a
+   low grade is genuinely the bad outcome. */
+.slab-10 .slab-grade, .slab-9 .slab-grade { background: linear-gradient(150deg, #0d7a3a, #10a44a); }
+.slab-8 .slab-grade, .slab-7 .slab-grade { background: linear-gradient(150deg, #1b6fbf, #2f6fd0); }
+.slab-6 .slab-grade, .slab-5 .slab-grade { background: linear-gradient(150deg, #b4700f, #e8912f); }
+.slab-low .slab-grade { background: linear-gradient(150deg, #9e2626, #d63a3a); }
+
+/* A 10 gets the foil treatment. Deliberately reserved for the top grade so
+   it stays meaningful — every card shimmering would say nothing. */
+.slab-10 .slab-grade {
+  background: linear-gradient(140deg, #0d7a3a, #35c6a8 40%, #4b8ee8 70%, #a97bff);
+}
+
+.card-type-tag {
+  display: inline-block; font-size: 10.5px; font-weight: 700;
+  letter-spacing: .07em; text-transform: uppercase;
+  padding: 2px 7px; border-radius: 4px;
+  background: var(--accent-soft); color: var(--accent);
+  border: 1px solid color-mix(in srgb, var(--accent) 30%, transparent);
+}
+
+/* --------------------------------------------------------------- phone */
+
+@media (max-width: 700px) {
+  main { padding: 14px 12px 60px; }
+  .topbar { padding: 10px 12px; }
+  .fields { grid-template-columns: 1fr; }
+  .grid { font-size: 13.5px; }
+}
--- a/static/sw.js
+++ b/static/sw.js
@ -0,0 +1,62 @@
+/* Service worker — the piece that makes this installable as a real app.
+ *
+ * Deliberately minimal, and deliberately network-first for everything.
+ * Caching the shell aggressively is the usual PWA advice, but here it would
+ * mean shipping a stale UI against a changed API and calling it offline
+ * support — this app cannot do anything useful without the network anyway,
+ * since grading is a live API call. So the cache exists only as a fallback
+ * for the app shell when the connection drops, and never for /api/.
+ */
+
+// Substituted server-side to the path this app is mounted under (e.g.
+// "/cards"), or left empty when served from the domain root — see
+// app.py's _static_templated. Every absolute reference below has to go
+// through this, since a service worker has no page URL of its own to
+// resolve relative paths against.
+const BASE = '__BASE__';
+
+const CACHE = 'card-grader-v1';
+const SHELL = [
+  `${BASE}/`,
+  `${BASE}/static/app.js`,
+  `${BASE}/static/style.css`,
+  `${BASE}/static/icon.svg`,
+  `${BASE}/static/manifest.json`,
+];
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE).then((cache) => cache.addAll(SHELL)).then(() => self.skipWaiting())
+  );
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches.keys()
+      .then((keys) => Promise.all(
+        keys.filter((k) => k !== CACHE).map((k) => caches.delete(k))))
+      .then(() => self.clients.claim())
+  );
+});
+
+self.addEventListener('fetch', (event) => {
+  const { request } = event;
+  if (request.method !== 'GET') return;
+
+  const url = new URL(request.url);
+  // Never cache the API. A stale grade or a stale settings blob would be
+  // worse than an honest failure.
+  if (url.pathname.startsWith(`${BASE}/api/`)) return;
+
+  event.respondWith(
+    fetch(request)
+      .then((response) => {
+        if (response && response.ok && url.origin === self.location.origin) {
+          const copy = response.clone();
+          caches.open(CACHE).then((cache) => cache.put(request, copy));
+        }
+        return response;
+      })
+      .catch(() => caches.match(request).then((hit) => hit || caches.match(`${BASE}/`)))
+  );
+});