Chart-position watchdog + browser notifications

[bootuz]

Summary

A daily background job that polls Apple's free iTunes RSS top-free charts for each watched app's primary genre across the storefronts where the app is available, persists what changed, and pushes browser notifications to any open dashboard tab. New `Charts` toolbar button opens a full-screen page with the Currently charted cards and a Recent activity feed.

Designed during a brainstorm session — the spec lives at `/Users/astemirboziev/.claude/plans/in-the-modal-for-validated-conway.md`. Key choices:

• Watchdog scope, not browser: this never tries to show "the full top-100 in country X"; it only emits events when one of your apps appears in one. Mostly silent for an app at Azri's scale today; high-signal when something does chart.
• Free data only: Apple's RSS feed (capped ~100/chart) is the single source of truth. No third-party API integration, no paid tier.
• No service worker: notifications only fire when a Keywordista tab is open. Worth it later but not for v1.
• Schema bounded: snapshot table holds only the latest position per `(app, country, chart, genre)` tuple — bounded by apps × countries, not by time. `chart_event` is append-only.

Architecture

```
Apple iTunes RSS ──┐
▼
RefreshChartsScheduler (daily, 04:00 UTC)
│
▼
ChartTrackerService ── diff vs chart_position_snapshot ── emit ChartEvent
│
▼
GET /api/v1/chart-events?since=… ◀── SPA polls every 30s ──── new Notification(…)
```

Backend additions:

• 3 new models + migrations (`AppStorefrontAvailability`, `ChartPositionSnapshot`, `ChartEvent`) plus a `primary_genre_id` column on `WatchedApp`.
• `AvailabilityProber` (175-storefront iTunes lookup, batched at 8 concurrent), `ITunesChartsClient` (timeout-wrapped RSS fetch), `ChartTrackerService` (per-(app,country) Fluent transactions).
• 4 new routes under `/api/v1` (chart-positions / chart-events / charts/refresh / apps/:id/availability/refresh).
• Composition wired in `Container.swift`; `AppsController.create` now kicks off an availability probe in a detached Task.

Frontend additions:

• `ChartsPage.svelte` + `ChartPositionCard.svelte` + `ChartActivityRow.svelte`.
• `lib/notifications.ts` (Notification API wrapper with localStorage opt-out memory) and `lib/chartEvents.ts` (singleton 30s poll, dedupe by event id, `lastSeenIso` persistence).
• Charts button + unread badge in the dashboard toolbar.

Diff algorithm

previous snapshot	new poll	event emitted	snapshot action
no row / position=null	found at #N	`entered`	upsert position=N
#M	found at #N (M≠N)	`moved`	update position=N
#M	not found	`exited`	update position=null
no row / position=null	not found	(none)	no-op
#M	found at #N (M=N)	(none)	bump `observed_at`

Pure-function form (`decideChartTransition`) extracted so all 7 cases are unit-tested without a DB.

Test plan

• `swift test` — 64 tests pass (11 new + 53 existing). New tests cover the 7-case diff matrix and RSS envelope decoder.
• `npm run check` — 0 errors, 0 warnings across 144 files.
• End-to-end against local stack:
  • Backend migrations applied cleanly on existing `db.sqlite`.
  • `POST /api/v1/charts/refresh` against Azri → ChartTracker logged `apps=1 charts=174 events=0` (correctly silent — Azri isn't in any top-100).
  • `WatchedApp.primary_genre_id` backfilled to `6017` automatically on first refresh.
  • Synthetic-state diff: inserted a fake "Azri was #50 in US Education" snapshot, re-ran refresh → `exited` event emitted with `prev_position=50, position=null`, surfaced by `GET /chart-events`.
• Reviewer: open `/charts` in a browser, click Enable on the permission CTA, click Check now (~30s for 174 fetches). Empty state should remain unless Azri unexpectedly charted.
• Reviewer (optional): temporarily add a watched app that is charted (e.g. Duolingo, appStoreId=570060128) and watch the first refresh emit several `entered` events with toasts.

Follow-ups (out of scope)

• Position history / sparklines / delta vs yesterday. Needs an append-only `chart_position_history` table; cheap to add but separate from the watchdog itself.
• Multi-chart-type / secondary-genre watching. Today MVP watches top-free × primary genre only. Adding top-paid / top-grossing or a secondary genre is a column on `chart_position_snapshot`, no schema migration.
• Service worker push. Notifications when the Keywordista tab is closed.
• Notification grouping / digest mode. Each event currently fires its own toast — fine at low volume.