whatsapp-sweeper 1.0.0__tar.gz

whatsapp_sweeper-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.DS_Store

whatsapp_sweeper-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Almog Baku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

whatsapp_sweeper-1.0.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: whatsapp-sweeper
+Version: 1.0.0
+Summary: Find and delete WhatsApp Desktop's bloated media cache, fast.
+Project-URL: Homepage, https://github.com/AlmogBaku/whatsapp-sweeper
+Project-URL: Repository, https://github.com/AlmogBaku/whatsapp-sweeper
+Project-URL: Issues, https://github.com/AlmogBaku/whatsapp-sweeper/issues
+Author-email: Almog Baku <almog.baku@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cleanup,macos,media,storage,whatsapp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Desktop Environment :: File Managers
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: pillow>=9.0
+Description-Content-Type: text/markdown
+
+# 🧹 WhatsApp Sweeper
+
+A local, fast tool for finding and deleting the media WhatsApp Desktop has quietly piled up on your Mac.
+
+## The problem
+
+WhatsApp Desktop downloads every photo, video, and voice note you ever receive and keeps it forever in a local cache. It's not unusual for that folder to quietly grow to 20-30GB — years of stickers, forwarded videos, and group-chat noise you'll never look at again.
+
+WhatsApp's engineers clearly track exactly which file belongs to which chat and sender — it's all sitting right there in their own local database. They just never shipped a way for you to see or clean it up. So here we are.
+
+## What it does
+
+WhatsApp Sweeper scans WhatsApp Desktop's media cache, cross-references it against WhatsApp's own local chat database to figure out who sent each file and from which chat, and gives you a simple visual grid — sorted by size, biggest offenders first — so you can select what to delete and reclaim the space in a couple of minutes.
+
+- **Sorted by size** — see what's actually eating your disk first
+- **Real thumbnails** — generated from the source files, not WhatsApp's blurry tiny cache
+- **Sender & group filters** — include/exclude by person or by group, combinable
+- **Finder-style selection** — click, shift-click for ranges, drag to multi-select
+- **Runs entirely on your machine** — no network calls, no accounts, nothing uploaded
+
+> [!NOTE]
+> This only reads WhatsApp's local cache and database to *display* information. It never sends anything anywhere — everything happens on `localhost`.
+
+## Requirements
+
+- macOS (this reads WhatsApp Desktop's macOS-specific cache and database — it won't work anywhere else)
+- WhatsApp Desktop, installed and opened at least once
+- Python 3.9+
+- [ffmpeg](https://ffmpeg.org) (optional, for sharper video thumbnails — falls back to WhatsApp's own cached preview frame if it's missing)
+
+## Quick start
+
+No install step needed — just run it:
+
+```bash
+uvx whatsapp-sweeper
+```
+
+or, with [pipx](https://pipx.pypa.io):
+
+```bash
+pipx run whatsapp-sweeper
+```
+
+Either one launches a local server and opens your browser to it automatically. Leave the terminal running while you use it; `Ctrl+C` to stop.
+
+## Using it
+
+- Click a thumbnail to open the file in its default app; double-click also works.
+- Click, `Shift`-click, `Cmd`-click, or drag across thumbnails to select multiple — like Finder's icon view.
+- Use the sidebar to filter by sender or by group/chat. Clicking a name cycles it through include-only → exclude → off, and both filters combine.
+- **Select all** selects everything matching the current filter, not just what's scrolled into view.
+
+> [!IMPORTANT]
+> Deleting is permanent — there is no trash or undo. Review your selection before confirming. WhatsApp will simply treat removed media as not-yet-downloaded if you ever need it again.
+
+## How sender resolution works
+
+Media files on disk are just UUIDs sitting in per-chat folders. To label each one with a sender and date, WhatsApp Sweeper reads `ChatStorage.sqlite` — the same database WhatsApp Desktop itself uses — joining the media entry to its message, then to the group member and chat, to resolve a display name. Older files that have aged out of WhatsApp's own message history simply show up as "Unknown" — that's WhatsApp's retention limit, not a bug here.

whatsapp_sweeper-1.0.0/README.md

@@ -0,0 +1,59 @@
+# 🧹 WhatsApp Sweeper
+
+A local, fast tool for finding and deleting the media WhatsApp Desktop has quietly piled up on your Mac.
+
+## The problem
+
+WhatsApp Desktop downloads every photo, video, and voice note you ever receive and keeps it forever in a local cache. It's not unusual for that folder to quietly grow to 20-30GB — years of stickers, forwarded videos, and group-chat noise you'll never look at again.
+
+WhatsApp's engineers clearly track exactly which file belongs to which chat and sender — it's all sitting right there in their own local database. They just never shipped a way for you to see or clean it up. So here we are.
+
+## What it does
+
+WhatsApp Sweeper scans WhatsApp Desktop's media cache, cross-references it against WhatsApp's own local chat database to figure out who sent each file and from which chat, and gives you a simple visual grid — sorted by size, biggest offenders first — so you can select what to delete and reclaim the space in a couple of minutes.
+
+- **Sorted by size** — see what's actually eating your disk first
+- **Real thumbnails** — generated from the source files, not WhatsApp's blurry tiny cache
+- **Sender & group filters** — include/exclude by person or by group, combinable
+- **Finder-style selection** — click, shift-click for ranges, drag to multi-select
+- **Runs entirely on your machine** — no network calls, no accounts, nothing uploaded
+
+> [!NOTE]
+> This only reads WhatsApp's local cache and database to *display* information. It never sends anything anywhere — everything happens on `localhost`.
+
+## Requirements
+
+- macOS (this reads WhatsApp Desktop's macOS-specific cache and database — it won't work anywhere else)
+- WhatsApp Desktop, installed and opened at least once
+- Python 3.9+
+- [ffmpeg](https://ffmpeg.org) (optional, for sharper video thumbnails — falls back to WhatsApp's own cached preview frame if it's missing)
+
+## Quick start
+
+No install step needed — just run it:
+
+```bash
+uvx whatsapp-sweeper
+```
+
+or, with [pipx](https://pipx.pypa.io):
+
+```bash
+pipx run whatsapp-sweeper
+```
+
+Either one launches a local server and opens your browser to it automatically. Leave the terminal running while you use it; `Ctrl+C` to stop.
+
+## Using it
+
+- Click a thumbnail to open the file in its default app; double-click also works.
+- Click, `Shift`-click, `Cmd`-click, or drag across thumbnails to select multiple — like Finder's icon view.
+- Use the sidebar to filter by sender or by group/chat. Clicking a name cycles it through include-only → exclude → off, and both filters combine.
+- **Select all** selects everything matching the current filter, not just what's scrolled into view.
+
+> [!IMPORTANT]
+> Deleting is permanent — there is no trash or undo. Review your selection before confirming. WhatsApp will simply treat removed media as not-yet-downloaded if you ever need it again.
+
+## How sender resolution works
+
+Media files on disk are just UUIDs sitting in per-chat folders. To label each one with a sender and date, WhatsApp Sweeper reads `ChatStorage.sqlite` — the same database WhatsApp Desktop itself uses — joining the media entry to its message, then to the group member and chat, to resolve a display name. Older files that have aged out of WhatsApp's own message history simply show up as "Unknown" — that's WhatsApp's retention limit, not a bug here.

whatsapp_sweeper-1.0.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "whatsapp-sweeper"
+version = "1.0.0"
+description = "Find and delete WhatsApp Desktop's bloated media cache, fast."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Almog Baku", email = "almog.baku@gmail.com" },
+]
+keywords = ["whatsapp", "macos", "storage", "cleanup", "media"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: MacOS X",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Topic :: Desktop Environment :: File Managers",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "Pillow>=9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/AlmogBaku/whatsapp-sweeper"
+Repository = "https://github.com/AlmogBaku/whatsapp-sweeper"
+Issues = "https://github.com/AlmogBaku/whatsapp-sweeper/issues"
+
+[project.scripts]
+whatsapp-sweeper = "whatsapp_sweeper.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/whatsapp_sweeper"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/whatsapp_sweeper/index.html" = "whatsapp_sweeper/index.html"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/whatsapp_sweeper",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+upload_to_vcs_release = true
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["feat", "fix", "perf", "refactor", "breaking", "chore", "docs", "style", "ci"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf", "refactor"]
+
+[tool.semantic_release.changelog]
+exclude_commit_patterns = [
+    "^chore",
+    "^docs",
+    "^style",
+    "^ci",
+]
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.remote]
+type = "github"
+
+[tool.semantic_release.publish]
+build_command = "uv build"

whatsapp_sweeper-1.0.0/src/whatsapp_sweeper/__init__.py

@@ -0,0 +1,3 @@
+"""WhatsApp Sweeper: find and delete WhatsApp Desktop's bloated media cache."""
+
+__version__ = "0.1.0"

whatsapp_sweeper-1.0.0/src/whatsapp_sweeper/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

whatsapp_sweeper-1.0.0/src/whatsapp_sweeper/index.html

@@ -0,0 +1,622 @@
+<title>WhatsApp Sweeper</title>
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='90'%3E%F0%9F%A7%B9%3C/text%3E%3C/svg%3E">
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    background: #121212;
+    color: #e8e8e8;
+    display: flex;
+    overflow: hidden;
+  }
+
+  /* ---- sidebar ---- */
+  #sidebar {
+    width: 260px;
+    flex-shrink: 0;
+    height: 100%;
+    min-height: 0;
+    background: #1a1a1a;
+    border-right: 1px solid #2a2a2a;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+  }
+  #brand {
+    display: flex; align-items: center; gap: 8px;
+    padding: 14px; border-bottom: 1px solid #2a2a2a; flex-shrink: 0;
+  }
+  #brand .logo {
+    font-size: 26px; line-height: 1; display: flex; align-items: center; justify-content: center;
+  }
+  #brand .name { font-size: 15px; font-weight: 700; color: #eee; }
+  #sidebar h2 { font-size: 14px; margin: 14px 14px 6px; color: #999; text-transform: uppercase; letter-spacing: .05em; }
+  #sidebar .hint { font-size: 11px; color: #777; margin: 0 14px 8px; line-height: 1.4; }
+  .filter-section { flex: 1; min-height: 0; display: flex; flex-direction: column; }
+  .filter-section + .filter-section { border-top: 1px solid #2a2a2a; }
+  .filter-search {
+    width: calc(100% - 28px);
+    margin: 4px 14px 8px; padding: 6px 8px; border-radius: 6px; border: 1px solid #333;
+    background: #111; color: #eee; font-size: 12px; outline: none;
+  }
+  .filter-search:focus { border-color: #4a8fe0; }
+  .filter-list { flex: 1; min-height: 0; overflow-y: auto; padding: 0 6px 12px; }
+  .sender-row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 6px 8px;
+    border-radius: 6px;
+    cursor: pointer;
+    font-size: 13px;
+  }
+  .sender-row:hover { background: #232323; }
+  .sender-row .chip {
+    width: 20px; height: 20px; border-radius: 5px; flex-shrink: 0;
+    border: 1px solid #444; display: flex; align-items: center; justify-content: center;
+    font-size: 12px; font-weight: bold;
+  }
+  .sender-row .name { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .sender-row .size { color: #888; font-size: 11px; }
+  .sender-row.include .chip { background: #1e5f2e; border-color: #2e8b40; color: #7ee08b; }
+  .sender-row.exclude .chip { background: #5f1e1e; border-color: #8b2e2e; color: #e07e7e; }
+  .sender-row.include { background: #14261a; }
+  .sender-row.exclude { background: #261414; }
+
+  /* ---- main ---- */
+  #main { flex: 1; height: 100%; min-height: 0; min-width: 0; display: flex; flex-direction: column; }
+  #toolbar {
+    display: flex; align-items: center; gap: 16px;
+    padding: 10px 16px; background: #1a1a1a; border-bottom: 1px solid #2a2a2a;
+    flex-shrink: 0;
+  }
+  #toolbar .stat { font-size: 13px; color: #aaa; }
+  #toolbar .spacer { flex: 1; }
+  #deleteBtn {
+    background: #7a1f1f; color: #fff; border: none; padding: 8px 16px;
+    border-radius: 6px; font-size: 13px; cursor: pointer;
+  }
+  #deleteBtn:disabled { background: #3a3a3a; color: #777; cursor: default; }
+  #deleteBtn:not(:disabled):hover { background: #9a2a2a; }
+  #selectAllBtn {
+    background: #2a2a2a; color: #ddd; border: 1px solid #3a3a3a; padding: 8px 16px;
+    border-radius: 6px; font-size: 13px; cursor: pointer;
+  }
+  #selectAllBtn:hover { background: #333; }
+
+  #grid {
+    flex: 1; min-height: 0; overflow-y: auto; padding: 16px;
+    display: grid; grid-template-columns: repeat(auto-fill, minmax(170px, 1fr));
+    gap: 12px; align-content: start;
+  }
+  .card {
+    position: relative; cursor: pointer; border: 2px solid transparent; border-radius: 8px;
+    aspect-ratio: 1 / 1;
+  }
+  /* overflow:hidden must live on this inner wrapper, not on .card itself:
+     overflow!=visible on a grid item zeroes its "automatic minimum size",
+     which makes the grid miscompute the row's auto track height. */
+  .card .frame {
+    position: absolute; inset: 0; overflow: hidden; border-radius: 8px; background: #1e1e1e;
+  }
+  .card.selected { border-color: #4a8fe0; }
+  .card img, .card .placeholder {
+    width: 100%; height: 100%; object-fit: cover; display: block;
+    -webkit-user-drag: none; user-select: none;
+  }
+  .card .placeholder {
+    display: flex; align-items: center; justify-content: center;
+    font-size: 12px; color: #888; background: #262626; text-transform: uppercase;
+  }
+  .card input[type=checkbox] {
+    position: absolute; top: 6px; left: 6px; width: 18px; height: 18px; z-index: 2;
+    cursor: pointer;
+  }
+  .card .overlay {
+    position: absolute; left: 0; right: 0; bottom: 0;
+    background: linear-gradient(transparent, rgba(0,0,0,.85));
+    padding: 18px 6px 5px; font-size: 10.5px; line-height: 1.35; color: #eee;
+    pointer-events: none;
+  }
+  .card .overlay .sender { font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .card .overlay .chat { color: #8fa8c9; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .card .overlay .meta { color: #bbb; display: flex; justify-content: space-between; gap: 4px; }
+  .card .duration {
+    position: absolute; top: 6px; right: 6px; background: rgba(0,0,0,.7);
+    padding: 2px 5px; border-radius: 4px; font-size: 10px;
+  }
+  #sentinel { height: 1px; grid-column: 1 / -1; }
+  #empty { color: #777; padding: 40px; text-align: center; grid-column: 1 / -1; }
+  #marquee {
+    position: fixed; border: 1px solid #4a8fe0; background: rgba(74,143,224,.15);
+    pointer-events: none; display: none; z-index: 50;
+  }
+</style>
+
+<div id="sidebar">
+  <div id="brand">
+    <span class="logo">🧹</span>
+    <span class="name">WhatsApp Sweeper</span>
+  </div>
+  <div class="filter-section">
+    <h2>Filter by sender</h2>
+    <div class="hint">Click a name to cycle: include only → exclude → off. Both can be active together.</div>
+    <input type="text" class="filter-search" id="senderSearch" placeholder="Search senders…">
+    <div class="filter-list" id="senderList"></div>
+  </div>
+  <div class="filter-section">
+    <h2>Filter by group / chat</h2>
+    <input type="text" class="filter-search" id="chatSearch" placeholder="Search groups…">
+    <div class="filter-list" id="chatList"></div>
+  </div>
+</div>
+
+<div id="main">
+  <div id="toolbar">
+    <span class="stat" id="totalStat">Loading…</span>
+    <span class="spacer"></span>
+    <span class="stat" id="selStat"></span>
+    <button id="selectAllBtn">Select all</button>
+    <button id="deleteBtn" disabled>Delete selected</button>
+  </div>
+  <div id="grid"></div>
+</div>
+
+<script>
+const state = {
+  include: new Set(),
+  exclude: new Set(),
+  includeChat: new Set(),
+  excludeChat: new Set(),
+  selected: new Set(),   // ids
+  selectedSizeOverride: null, // set by "select all" (exact server total); cleared on any manual toggle
+  itemsById: new Map(),  // id -> item, for size lookups
+  lastClickedId: null,   // shift-click range anchor
+  filteredTotal: 0,      // total_count for the current filter (from last /api/items)
+  nextOffset: 0,
+  loading: false,
+  done: false,
+};
+
+function humanSize(bytes) {
+  if (bytes == null) return '';
+  const units = ['B','KB','MB','GB','TB'];
+  let i = 0, v = bytes;
+  while (v >= 1024 && i < units.length - 1) { v /= 1024; i++; }
+  return `${v.toFixed(v >= 10 || i === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+function humanDuration(sec) {
+  if (sec == null) return null;
+  sec = Math.round(sec);
+  const m = Math.floor(sec / 60), s = sec % 60;
+  return `${m}:${String(s).padStart(2, '0')}`;
+}
+
+function humanDate(epoch) {
+  if (!epoch) return '';
+  const d = new Date(epoch * 1000);
+  return d.toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' });
+}
+
+// Generic filter-section wiring: shared by "sender" and "chat" (group) filters.
+const filterSections = {
+  sender: { endpoint: '/api/senders', listId: 'senderList', searchId: 'senderSearch', include: state.include, exclude: state.exclude },
+  chat: { endpoint: '/api/chats', listId: 'chatList', searchId: 'chatSearch', include: state.includeChat, exclude: state.excludeChat },
+};
+
+async function loadFilterSection(key) {
+  const cfg = filterSections[key];
+  const res = await fetch(cfg.endpoint);
+  const rows = await res.json();
+  const list = document.getElementById(cfg.listId);
+  list.innerHTML = '';
+  for (const s of rows) {
+    const row = document.createElement('div');
+    row.className = 'sender-row';
+    row.dataset.name = s.name.toLowerCase();
+    row.innerHTML = `<span class="chip"></span><span class="name">${escapeHtml(s.name)}</span><span class="size">${humanSize(s.total_size)}</span>`;
+    row.onclick = () => cycleFilter(key, s.name, row);
+    list.appendChild(row);
+  }
+}
+
+function cycleFilter(key, name, row) {
+  const { include, exclude } = filterSections[key];
+  if (include.has(name)) {
+    include.delete(name);
+    exclude.add(name);
+    row.className = 'sender-row exclude';
+    row.querySelector('.chip').textContent = '−';
+  } else if (exclude.has(name)) {
+    exclude.delete(name);
+    row.className = 'sender-row';
+    row.querySelector('.chip').textContent = '';
+  } else {
+    include.add(name);
+    row.className = 'sender-row include';
+    row.querySelector('.chip').textContent = '✓';
+  }
+  resetGrid();
+}
+
+function wireFilterSearch(key) {
+  const cfg = filterSections[key];
+  document.getElementById(cfg.searchId).addEventListener('input', (e) => {
+    const q = e.target.value.trim().toLowerCase();
+    for (const row of document.getElementById(cfg.listId).children) {
+      row.style.display = row.dataset.name.includes(q) ? '' : 'none';
+    }
+  });
+}
+
+function escapeHtml(s) {
+  const d = document.createElement('div');
+  d.textContent = s ?? '';
+  return d.innerHTML;
+}
+
+function resetGrid() {
+  document.getElementById('grid').innerHTML = '';
+  state.selected.clear();
+  state.selectedSizeOverride = null;
+  state.lastClickedId = null;
+  updateSelStat();
+  state.nextOffset = 0;
+  state.done = false;
+  loadMore();
+}
+
+async function loadMore() {
+  if (state.loading || state.done) return;
+  state.loading = true;
+  const params = new URLSearchParams({
+    offset: state.nextOffset,
+    limit: 60,
+    include: [...state.include].join(','),
+    exclude: [...state.exclude].join(','),
+    include_chat: [...state.includeChat].join(','),
+    exclude_chat: [...state.excludeChat].join(','),
+  });
+  const res = await fetch('/api/items?' + params);
+  const data = await res.json();
+  state.filteredTotal = data.total_count;
+  document.getElementById('totalStat').textContent =
+    `${data.total_count.toLocaleString()} files · ${humanSize(data.total_size)}`;
+  updateSelectAllLabel();
+
+  const grid = document.getElementById('grid');
+  const sentinel = document.getElementById('sentinel');
+  if (sentinel) sentinel.remove();
+
+  if (data.items.length === 0 && state.nextOffset === 0) {
+    const empty = document.createElement('div');
+    empty.id = 'empty';
+    empty.textContent = 'No files match this filter.';
+    grid.appendChild(empty);
+  }
+
+  for (const item of data.items) {
+    grid.appendChild(renderCard(item));
+  }
+
+  if (data.next_offset != null) {
+    state.nextOffset = data.next_offset;
+    const s = document.createElement('div');
+    s.id = 'sentinel';
+    grid.appendChild(s);
+    observer.observe(s);
+  } else {
+    state.done = true;
+  }
+  state.loading = false;
+}
+
+function renderCard(item) {
+  state.itemsById.set(item.id, item);
+
+  const card = document.createElement('div');
+  const preSelected = state.selected.has(item.id);
+  card.className = preSelected ? 'card selected' : 'card';
+  card.dataset.id = item.id;
+
+  const frame = document.createElement('div');
+  frame.className = 'frame';
+  card.appendChild(frame);
+
+  const cb = document.createElement('input');
+  cb.type = 'checkbox';
+  cb.checked = preSelected;
+  cb.onclick = (e) => {
+    e.stopPropagation();
+    setCardSelected(item.id, cb.checked);
+    state.lastClickedId = item.id;
+    updateSelStat();
+  };
+  card.appendChild(cb);
+
+  if (item.has_thumb) {
+    const img = document.createElement('img');
+    img.loading = 'lazy';
+    img.draggable = false;
+    img.src = `/thumb/${item.id}`;
+    img.onerror = () => { img.replaceWith(placeholder(item.ext)); };
+    frame.appendChild(img);
+  } else {
+    frame.appendChild(placeholder(item.ext));
+  }
+
+  const dur = humanDuration(item.duration);
+  if (dur) {
+    const d = document.createElement('div');
+    d.className = 'duration';
+    d.textContent = dur;
+    frame.appendChild(d);
+  }
+
+  const overlay = document.createElement('div');
+  overlay.className = 'overlay';
+  const showChat = item.chat && item.chat !== item.sender;
+  overlay.innerHTML = `
+    <div class="sender">${escapeHtml(item.sender)}</div>
+    ${showChat ? `<div class="chat">${escapeHtml(item.chat)}</div>` : ''}
+    <div class="meta"><span>${humanSize(item.size)}</span><span>${humanDate(item.date)}</span></div>
+  `;
+  frame.appendChild(overlay);
+
+  // Finder-like selection: click = select only, shift = range, cmd/ctrl = toggle.
+  // Double-click opens the file.
+  card.addEventListener('click', (e) => {
+    if (e.shiftKey && state.lastClickedId != null) {
+      selectRange(state.lastClickedId, item.id);
+    } else if (e.metaKey || e.ctrlKey) {
+      setCardSelected(item.id, !state.selected.has(item.id));
+      state.lastClickedId = item.id;
+    } else {
+      clearSelection();
+      setCardSelected(item.id, true);
+      state.lastClickedId = item.id;
+    }
+    updateSelStat();
+  });
+  card.addEventListener('dblclick', () => {
+    fetch('/api/open', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id: item.id }),
+    });
+  });
+
+  return card;
+}
+
+function placeholder(ext) {
+  const p = document.createElement('div');
+  p.className = 'placeholder';
+  p.textContent = ext || 'file';
+  return p;
+}
+
+function setCardSelected(id, selected) {
+  state.selectedSizeOverride = null; // manual change invalidates the "select all" exact total
+  const card = document.querySelector(`.card[data-id="${id}"]`);
+  if (selected) {
+    state.selected.add(id);
+    if (card) card.classList.add('selected');
+  } else {
+    state.selected.delete(id);
+    if (card) card.classList.remove('selected');
+  }
+  if (card) {
+    const cb = card.querySelector('input[type=checkbox]');
+    if (cb) cb.checked = selected;
+  }
+}
+
+function clearSelection() {
+  for (const id of [...state.selected]) setCardSelected(id, false);
+}
+
+function selectRange(fromId, toId) {
+  const ids = [...document.querySelectorAll('.card')].map(c => Number(c.dataset.id));
+  const i1 = ids.indexOf(fromId), i2 = ids.indexOf(toId);
+  if (i1 === -1 || i2 === -1) {
+    clearSelection();
+    setCardSelected(toId, true);
+    return;
+  }
+  const [lo, hi] = i1 < i2 ? [i1, i2] : [i2, i1];
+  clearSelection();
+  for (let i = lo; i <= hi; i++) setCardSelected(ids[i], true);
+}
+
+function updateSelStat() {
+  const n = state.selected.size;
+  let total = state.selectedSizeOverride;
+  if (total == null) {
+    total = 0;
+    for (const id of state.selected) {
+      const it = state.itemsById.get(id);
+      if (it) total += it.size;
+    }
+  }
+  document.getElementById('selStat').textContent = n ? `${n} selected · ${humanSize(total)}` : '';
+  document.getElementById('deleteBtn').disabled = n === 0;
+  updateSelectAllLabel();
+}
+
+function updateSelectAllLabel() {
+  const btn = document.getElementById('selectAllBtn');
+  const allSelected = state.filteredTotal > 0 && state.selected.size >= state.filteredTotal;
+  btn.textContent = allSelected ? 'Deselect all' : `Select all ${state.filteredTotal.toLocaleString()}`;
+}
+
+document.getElementById('selectAllBtn').onclick = async () => {
+  const allSelected = state.filteredTotal > 0 && state.selected.size >= state.filteredTotal;
+  if (allSelected) {
+    clearSelection();
+    updateSelStat();
+    return;
+  }
+  const params = new URLSearchParams({
+    include: [...state.include].join(','),
+    exclude: [...state.exclude].join(','),
+    include_chat: [...state.includeChat].join(','),
+    exclude_chat: [...state.excludeChat].join(','),
+  });
+  const res = await fetch('/api/select_all?' + params);
+  const data = await res.json();
+  state.selected = new Set(data.ids);
+  state.selectedSizeOverride = data.total_size;
+  // Reflect selection on whatever cards are already rendered.
+  for (const card of document.querySelectorAll('.card')) {
+    const id = Number(card.dataset.id);
+    const sel = state.selected.has(id);
+    card.classList.toggle('selected', sel);
+    const cb = card.querySelector('input[type=checkbox]');
+    if (cb) cb.checked = sel;
+  }
+  updateSelStat();
+};
+
+// ---- Finder-style rubber-band drag selection ----
+const marquee = document.createElement('div');
+marquee.id = 'marquee';
+document.body.appendChild(marquee);
+
+let dragStart = null;
+let dragMoved = false;
+let dragAdditive = false;
+let dragSnapshot = null;
+let lastMouse = { x: 0, y: 0 };
+let autoScrollRAF = null;
+
+const AUTOSCROLL_EDGE = 50;   // px from top/bottom edge that triggers scrolling
+const AUTOSCROLL_SPEED = 16;  // max px scrolled per animation frame
+
+document.getElementById('grid').addEventListener('mousedown', (e) => {
+  // Only the checkbox opts out of drag-select; dragging that starts on top of
+  // a thumbnail should still paint-select, like Finder icon view.
+  if (e.button !== 0 || e.target.closest('input[type=checkbox]')) return;
+  dragStart = { x: e.clientX, y: e.clientY };
+  dragMoved = false;
+  dragAdditive = e.shiftKey || e.metaKey || e.ctrlKey;
+  dragSnapshot = new Set(state.selected);
+  if (!dragAdditive) clearSelection();
+  e.preventDefault();
+});
+
+document.addEventListener('mousemove', (e) => {
+  lastMouse = { x: e.clientX, y: e.clientY };
+  if (!dragStart) return;
+  if (!dragMoved) {
+    // Don't show the marquee (or touch selection) for a plain click with no
+    // real movement — let the card's own click handler own that case.
+    const moved = Math.abs(e.clientX - dragStart.x) > 3 || Math.abs(e.clientY - dragStart.y) > 3;
+    if (!moved) return;
+    dragMoved = true;
+    marquee.style.display = 'block';
+    if (!autoScrollRAF) autoScrollRAF = requestAnimationFrame(autoScrollTick);
+  }
+  updateMarquee(e.clientX, e.clientY);
+  applyMarqueeSelection();
+});
+
+document.addEventListener('mouseup', () => {
+  if (!dragStart) return;
+  dragStart = null;
+  dragMoved = false;
+  marquee.style.display = 'none';
+  updateSelStat();
+});
+
+// Autoscroll the grid while dragging near its top/bottom edge, like Finder.
+// The marquee anchor moves with the content so it stays pinned to the same
+// pixel as the grid scrolls underneath the still-held cursor.
+function autoScrollTick() {
+  if (!dragStart) { autoScrollRAF = null; return; }
+  autoScrollRAF = requestAnimationFrame(autoScrollTick);
+  if (!dragMoved) return;
+
+  const grid = document.getElementById('grid');
+  const rect = grid.getBoundingClientRect();
+  const y = lastMouse.y;
+  let dy = 0;
+  if (y < rect.top + AUTOSCROLL_EDGE) {
+    dy = -AUTOSCROLL_SPEED * Math.min(1, (rect.top + AUTOSCROLL_EDGE - y) / AUTOSCROLL_EDGE);
+  } else if (y > rect.bottom - AUTOSCROLL_EDGE) {
+    dy = AUTOSCROLL_SPEED * Math.min(1, (y - (rect.bottom - AUTOSCROLL_EDGE)) / AUTOSCROLL_EDGE);
+  }
+  if (dy === 0) return;
+
+  const before = grid.scrollTop;
+  grid.scrollTop += dy;
+  const actualDy = grid.scrollTop - before;
+  if (actualDy === 0) return;
+
+  dragStart.y -= actualDy;
+  updateMarquee(lastMouse.x, lastMouse.y);
+  applyMarqueeSelection();
+}
+
+function updateMarquee(x, y) {
+  const left = Math.min(x, dragStart.x), top = Math.min(y, dragStart.y);
+  const width = Math.abs(x - dragStart.x), height = Math.abs(y - dragStart.y);
+  marquee.style.left = left + 'px';
+  marquee.style.top = top + 'px';
+  marquee.style.width = width + 'px';
+  marquee.style.height = height + 'px';
+  marquee._rect = { left, top, right: left + width, bottom: top + height };
+}
+
+function rectsIntersect(a, b) {
+  return !(b.left > a.right || b.right < a.left || b.top > a.bottom || b.bottom < a.top);
+}
+
+function applyMarqueeSelection() {
+  const mRect = marquee._rect;
+  for (const card of document.querySelectorAll('.card')) {
+    const id = Number(card.dataset.id);
+    const intersects = rectsIntersect(mRect, card.getBoundingClientRect());
+    setCardSelected(id, intersects || (dragAdditive && dragSnapshot.has(id)));
+  }
+  updateSelStat();
+}
+
+document.getElementById('deleteBtn').onclick = async () => {
+  const n = state.selected.size;
+  let total = 0;
+  for (const id of state.selected) {
+    const it = state.itemsById.get(id);
+    if (it) total += it.size;
+  }
+  if (!confirm(`Permanently delete ${n} file${n === 1 ? '' : 's'} (${humanSize(total)})? This cannot be undone.`)) {
+    return;
+  }
+  const ids = [...state.selected];
+  const res = await fetch('/api/delete', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ ids }),
+  });
+  await res.json();
+  // Full refresh: re-pull the (now smaller) filtered list and both filter
+  // panels, rather than just plucking deleted cards out of the DOM.
+  state.itemsById.clear();
+  resetGrid();
+  loadFilterSection('sender');
+  loadFilterSection('chat');
+};
+
+const observer = new IntersectionObserver((entries) => {
+  for (const e of entries) if (e.isIntersecting) loadMore();
+});
+
+loadFilterSection('sender');
+loadFilterSection('chat');
+wireFilterSearch('sender');
+wireFilterSearch('chat');
+loadMore();
+</script>

whatsapp_sweeper-1.0.0/src/whatsapp_sweeper/server.py

@@ -0,0 +1,395 @@
+#!/usr/bin/env python3
+"""WhatsApp Sweeper: find and delete WhatsApp Desktop's bloated media cache.
+
+Run: whatsapp-sweeper
+Then open http://localhost:8765 (opened automatically).
+"""
+import hashlib
+import http.server
+import json
+import os
+import socketserver
+import sqlite3
+import subprocess
+import sys
+import tempfile
+import threading
+import urllib.parse
+import webbrowser
+from pathlib import Path
+
+from PIL import Image
+
+MEDIA_DIR = Path(os.path.expanduser(
+    "~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/Message/Media"
+))
+DB_PATH = os.path.expanduser(
+    "~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite"
+)
+STATIC_DIR = Path(__file__).parent
+PORT = 8765
+SIDECAR_EXTS = {".thumb", ".favicon", ".mmsthumb"}
+APPLE_EPOCH_OFFSET = 978307200  # 2001-01-01 -> unix epoch
+
+IMAGE_EXTS = {"jpg", "jpeg", "png", "webp", "gif", "bmp", "tiff"}
+VIDEO_EXTS = {"mp4", "mov", "m4v", "3gp", "avi", "mkv"}
+THUMB_SIZE = 320
+THUMB_CACHE_DIR = Path(tempfile.gettempdir()) / "whatsapp-sweeper-thumbs"
+THUMB_CACHE_DIR.mkdir(exist_ok=True)
+
+RECORDS = {}   # id -> record dict, mutated on delete
+ORDER = []     # ids sorted by size desc, fixed at startup
+
+DB_QUERY = """
+    SELECT
+        mi.ZMEDIALOCALPATH AS path,
+        mi.ZMOVIEDURATION AS duration,
+        m.ZMESSAGEDATE AS msg_date,
+        m.ZISFROMME AS is_from_me,
+        m.ZFROMJID AS from_jid,
+        gm.ZMEMBERJID AS member_jid,
+        pn_member.ZPUSHNAME AS member_pushname,
+        pn_direct.ZPUSHNAME AS direct_pushname,
+        cs.ZPARTNERNAME AS chat_name,
+        cs.ZSESSIONTYPE AS session_type
+    FROM ZWAMEDIAITEM mi
+    JOIN ZWAMESSAGE m ON m.Z_PK = mi.ZMESSAGE
+    LEFT JOIN ZWAGROUPMEMBER gm ON gm.Z_PK = m.ZGROUPMEMBER
+    LEFT JOIN ZWAPROFILEPUSHNAME pn_member ON pn_member.ZJID = gm.ZMEMBERJID
+    LEFT JOIN ZWAPROFILEPUSHNAME pn_direct ON pn_direct.ZJID = m.ZFROMJID
+    JOIN ZWACHATSESSION cs ON cs.Z_PK = m.ZCHATSESSION
+    WHERE mi.ZMEDIALOCALPATH IS NOT NULL
+"""
+
+
+def load_db_index():
+    """rel path (inside MEDIA_DIR) -> {sender, chat, duration, date}"""
+    index = {}
+    conn = sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True)
+    conn.row_factory = sqlite3.Row
+    for row in conn.execute(DB_QUERY):
+        rel = row["path"]
+        if rel.startswith("Media/"):
+            rel = rel[len("Media/"):]
+
+        if row["is_from_me"]:
+            sender = "Me"
+        elif row["member_pushname"]:
+            sender = row["member_pushname"]
+        elif row["direct_pushname"]:
+            sender = row["direct_pushname"]
+        elif row["session_type"] == 0 and row["chat_name"]:
+            sender = row["chat_name"]
+        else:
+            jid = row["member_jid"] or row["from_jid"] or ""
+            sender = jid.split("@")[0] if jid else "Unknown"
+
+        date = None
+        if row["msg_date"] is not None:
+            date = row["msg_date"] + APPLE_EPOCH_OFFSET
+
+        index[rel] = {
+            "sender": sender or "Unknown",
+            "chat": row["chat_name"] or sender or "Unknown",
+            "duration": row["duration"],
+            "date": date,
+        }
+    conn.close()
+    return index
+
+
+def scan_media():
+    db_index = load_db_index()
+    next_id = 0
+    for root, _dirs, files in os.walk(MEDIA_DIR):
+        for name in files:
+            if name.startswith("."):
+                continue
+            ext = os.path.splitext(name)[1].lower()
+            if ext in SIDECAR_EXTS:
+                continue
+            full = Path(root) / name
+            rel = str(full.relative_to(MEDIA_DIR))
+            try:
+                st = full.stat()
+            except OSError:
+                continue
+            meta = db_index.get(rel)
+            ext_lower = ext.lstrip(".").lower()
+            is_video = ext_lower in VIDEO_EXTS
+            has_sidecar_thumb = os.path.exists(os.path.splitext(full)[0] + ".thumb")
+            RECORDS[next_id] = {
+                "id": next_id,
+                "path": str(full),
+                "name": name,
+                "ext": ext_lower,
+                "size": st.st_size,
+                "date": meta["date"] if meta and meta["date"] else st.st_mtime,
+                "duration": meta["duration"] if meta and is_video else None,
+                "sender": meta["sender"] if meta else "Unknown",
+                "chat": meta["chat"] if meta else "Unknown",
+                "has_thumb": ext_lower in IMAGE_EXTS or is_video or has_sidecar_thumb,
+            }
+            next_id += 1
+    ORDER[:] = sorted(RECORDS.keys(), key=lambda i: RECORDS[i]["size"], reverse=True)
+    total_size = sum(r["size"] for r in RECORDS.values())
+    print(f"Indexed {len(RECORDS)} files, {total_size / (1024**3):.1f} GB")
+
+
+def thumb_cache_path(path):
+    key = hashlib.sha1(path.encode()).hexdigest()
+    return THUMB_CACHE_DIR / f"{key}.jpg"
+
+
+def get_or_make_thumb(rec):
+    """Real thumbnail generated from the source file (cached to disk),
+    falling back to WhatsApp's own tiny cached .thumb sidecar on failure."""
+    cache_path = thumb_cache_path(rec["path"])
+    if cache_path.exists():
+        return cache_path
+
+    ext = rec["ext"]
+    try:
+        if ext in IMAGE_EXTS:
+            with Image.open(rec["path"]) as im:
+                im = im.convert("RGB")
+                im.thumbnail((THUMB_SIZE, THUMB_SIZE))
+                im.save(cache_path, "JPEG", quality=85)
+            return cache_path
+        elif ext in VIDEO_EXTS:
+            result = subprocess.run(
+                [
+                    "ffmpeg", "-y", "-ss", "0.5", "-i", rec["path"],
+                    "-frames:v", "1", "-vf", f"scale={THUMB_SIZE}:-1",
+                    str(cache_path),
+                ],
+                capture_output=True, timeout=15,
+            )
+            if result.returncode == 0 and cache_path.exists():
+                return cache_path
+    except Exception as exc:
+        print(f"thumb generation failed for {rec['path']}: {exc}")
+
+    legacy = os.path.splitext(rec["path"])[0] + ".thumb"
+    return Path(legacy) if os.path.exists(legacy) else None
+
+
+def compute_agg(key):
+    agg = {}
+    for r in RECORDS.values():
+        s = agg.setdefault(r[key], {"name": r[key], "count": 0, "total_size": 0})
+        s["count"] += 1
+        s["total_size"] += r["size"]
+    return sorted(agg.values(), key=lambda s: s["total_size"], reverse=True)
+
+
+def compute_senders():
+    return compute_agg("sender")
+
+
+def compute_chats():
+    return compute_agg("chat")
+
+
+def filter_ids(include, exclude, include_chat, exclude_chat):
+    for i in ORDER:
+        r = RECORDS.get(i)
+        if r is None:
+            continue
+        if include and r["sender"] not in include:
+            continue
+        if r["sender"] in exclude:
+            continue
+        if include_chat and r["chat"] not in include_chat:
+            continue
+        if r["chat"] in exclude_chat:
+            continue
+        yield i, r
+
+
+def item_json(i, r):
+    return {
+        "id": i,
+        "name": r["name"],
+        "ext": r["ext"],
+        "size": r["size"],
+        "date": r["date"],
+        "duration": r["duration"],
+        "sender": r["sender"],
+        "chat": r["chat"],
+        "has_thumb": r["has_thumb"],
+    }
+
+
+class Handler(http.server.BaseHTTPRequestHandler):
+    def log_message(self, fmt, *args):
+        pass
+
+    def _send_json(self, obj, status=200):
+        body = json.dumps(obj).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _serve_bytes(self, data, content_type):
+        self.send_response(200)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_GET(self):
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path == "/":
+            try:
+                data = (STATIC_DIR / "index.html").read_bytes()
+            except OSError:
+                self.send_error(404)
+                return
+            self._serve_bytes(data, "text/html; charset=utf-8")
+        elif parsed.path == "/api/items":
+            self._api_items(parsed)
+        elif parsed.path == "/api/senders":
+            self._send_json(compute_senders())
+        elif parsed.path == "/api/chats":
+            self._send_json(compute_chats())
+        elif parsed.path == "/api/select_all":
+            self._api_select_all(parsed)
+        elif parsed.path.startswith("/thumb/"):
+            self._serve_thumb(parsed.path[len("/thumb/"):])
+        else:
+            self.send_error(404)
+
+    @staticmethod
+    def _parse_filters(qs):
+        include = {s for s in qs.get("include", [""])[0].split(",") if s}
+        exclude = {s for s in qs.get("exclude", [""])[0].split(",") if s}
+        include_chat = {s for s in qs.get("include_chat", [""])[0].split(",") if s}
+        exclude_chat = {s for s in qs.get("exclude_chat", [""])[0].split(",") if s}
+        return include, exclude, include_chat, exclude_chat
+
+    def _api_items(self, parsed):
+        qs = urllib.parse.parse_qs(parsed.query)
+        try:
+            offset = int(qs.get("offset", ["0"])[0])
+            limit = min(int(qs.get("limit", ["60"])[0]), 200)
+        except ValueError:
+            offset, limit = 0, 60
+
+        matched = list(filter_ids(*self._parse_filters(qs)))
+        total_count = len(matched)
+        total_size = sum(r["size"] for _, r in matched)
+        page = matched[offset: offset + limit]
+        next_offset = offset + limit if offset + limit < total_count else None
+        self._send_json({
+            "items": [item_json(i, r) for i, r in page],
+            "total_count": total_count,
+            "total_size": total_size,
+            "next_offset": next_offset,
+        })
+
+    def _api_select_all(self, parsed):
+        qs = urllib.parse.parse_qs(parsed.query)
+        matched = list(filter_ids(*self._parse_filters(qs)))
+        self._send_json({
+            "ids": [i for i, _r in matched],
+            "total_count": len(matched),
+            "total_size": sum(r["size"] for _, r in matched),
+        })
+
+    def _serve_thumb(self, id_str):
+        try:
+            rec = RECORDS[int(id_str)]
+        except (KeyError, ValueError):
+            self.send_error(404)
+            return
+        thumb_path = get_or_make_thumb(rec)
+        if thumb_path is None:
+            self.send_error(404)
+            return
+        try:
+            data = thumb_path.read_bytes()
+        except OSError:
+            self.send_error(404)
+            return
+        self._serve_bytes(data, "image/jpeg")
+
+    def do_POST(self):
+        parsed = urllib.parse.urlparse(self.path)
+        length = int(self.headers.get("Content-Length", 0) or 0)
+        raw = self.rfile.read(length) if length else b"{}"
+        try:
+            payload = json.loads(raw or b"{}")
+        except json.JSONDecodeError:
+            payload = {}
+
+        if parsed.path == "/api/open":
+            self._api_open(payload)
+        elif parsed.path == "/api/delete":
+            self._api_delete(payload)
+        else:
+            self.send_error(404)
+
+    def _api_open(self, payload):
+        rec = RECORDS.get(payload.get("id"))
+        if rec is None:
+            self._send_json({"ok": False, "error": "not found"}, 404)
+            return
+        subprocess.run(["open", rec["path"]])
+        self._send_json({"ok": True})
+
+    def _api_delete(self, payload):
+        ids = payload.get("ids", [])
+        results = {}
+        for id_ in ids:
+            rec = RECORDS.get(id_)
+            if rec is None:
+                results[str(id_)] = False
+                continue
+            try:
+                os.remove(rec["path"])
+            except OSError as exc:
+                results[str(id_)] = False
+                print(f"delete failed for {rec['path']}: {exc}")
+                continue
+            base = os.path.splitext(rec["path"])[0]
+            for ext in SIDECAR_EXTS:
+                try:
+                    os.remove(base + ext)
+                except OSError:
+                    pass
+            del RECORDS[id_]
+            results[str(id_)] = True
+        self._send_json({"results": results})
+
+
+def main():
+    if sys.platform != "darwin":
+        sys.exit(
+            "WhatsApp Sweeper only supports macOS (it reads WhatsApp Desktop's "
+            "local media cache and chat database, which only exist there)."
+        )
+    if not MEDIA_DIR.exists():
+        sys.exit(
+            f"Couldn't find WhatsApp Desktop's media folder at:\n  {MEDIA_DIR}\n"
+            "Is WhatsApp Desktop installed, and have you opened it at least once?"
+        )
+    if not os.path.exists(DB_PATH):
+        sys.exit(f"Couldn't find WhatsApp's chat database at:\n  {DB_PATH}")
+
+    scan_media()
+    with socketserver.ThreadingTCPServer(("127.0.0.1", PORT), Handler) as httpd:
+        httpd.allow_reuse_address = True
+        url = f"http://localhost:{PORT}"
+        print(f"Serving on {url}")
+        threading.Timer(0.5, lambda: webbrowser.open(url)).start()
+        try:
+            httpd.serve_forever()
+        except KeyboardInterrupt:
+            pass
+
+
+if __name__ == "__main__":
+    main()