[DyRize]

Summary

Adds a usage recap: one calendar week, month or year at a time, stepping back through time with Previous / Next, rendered as a small Pokédex-style readout. It reports what already happened: no goal, no reward, nothing to do.

What the card shows: the total, one meter per day (per month in the year view), the change against the previous period, best day, best streak, active days, and the individuals graduated in that period, next to the Pokémon being raised. The title is the period itself (Sep 14 – 20, 2026, September 2026, 2026), so the card says on its own what it covers.

Where the history comes from. Providers only report the current month (monthDaily), so on the 3rd a week would lose four days and a year would be out of reach. Every refresh now copies the daily totals into a small ledger in UserDefaults (UsageLedger):

• a day never goes down (max-merge), so a rotated or pruned log cannot erase days that really happened;
• it keeps this year and the last one, the most any view compares against (about 20 KB at most);
• it is derived data, like the usage cache: not part of the companion save, not transferred, rebuilt by the next refresh.

"No usage" vs "not recorded yet". The ledger also stores the first day it can vouch for. The month series lists every day since the 1st, empty ones included, so the first refresh vouches for the whole month so far. Days before that point, and days still ahead, are drawn as unknown rather than as zeros (dimmer grid, "no data" for VoiceOver), and Previous stops where the history starts.

Comparisons that do not lie:

• a period still running is compared over the same number of days: on the 18th, September 1–18 against August 1–18, not against the whole of August. A caption under the card says so;
• a finished period is compared whole;
• no chip at all unless the ledger covers the previous period from its first day, so a fresh install never claims a jump over days it never saw.

Weeks start on the region's first weekday; periods use a Gregorian calendar whatever the system calendar, so a year runs January to December and day keys match LocalUsageReader.localDayFormatter.

Entry point: a chart button at the end of the "This week / This month" row on Home.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Documentation
• Other:

UI changes

Before	After
Home's week/month row shows the "This week" and "This month" totals and nothing else.	A chart button (chart.bar.xaxis) at the end of that row opens the recap inside the popover, like Settings: Back (Esc works too), a Week / Month / Year picker, Previous / Next, the card, a best-day line, and a note on how the chip compares while a period is running. There is no image export.

Screenshots (English, rendered from this branch):

The card is drawn with explicit colors, so it looks the same in light and dark mode.

Checklist

• swift build and swift test pass locally
• PR title and description are written in English
• UI changes are described above (before/after — images optional)
• No copyrighted assets, secrets, or private tooling references are committed (see CONTRIBUTING)
• Tests were added or updated for this change

scripts/test-gate.sh: 1289 tests, 12 skipped, 0 failures, logic-core line coverage 94.20% (UsageRecap.swift added to the logic core, 96.7% of its lines). 19 tests cover the recap: ledger merge, coverage and pruning, junk in hand-edited defaults, the first refresh filling the ledger, retention of last year, week start by region, month and year stepping (31 March back to February), meters per scope, unknown vs zero days, same-day comparison for running periods, whole comparison for finished ones, no comparison over a half-covered period, best streak cut at the period's edges, graduations in the period, where Previous stops, and rendering in all seven languages for every scope. New branches were checked with llvm-cov --show-regions rather than the coverage number; the remaining ^0 regions are API-forced unwraps on Gregorian arithmetic. Every rule above was verified by injecting the defect and watching its test fail.

Two defects found while building this are recorded in docs/reference/defect-log.md: the ledger was first written right after phase 1 of the refresh, before monthDaily exists, which left the first refresh empty; and an early version judged coverage on the newest day of the previous window instead of the oldest, which inflated the delta.

[chattymin]

Please remove the PNG export functionality before this can be merged. Keep the in-app Usage Recap, but remove Copy Image / Save PNG, RecapExport and its preload/file-writing path, export-only localization strings, and export tests. Exporting a composed image that contains Pokémon sprites conflicts with this repository's copyrighted-asset export policy in CONTRIBUTING.md.

[DyRize]

Done, thanks for the clear pointer to the policy. The in-app recap stays; Copy image / Save…, RecapExport with its sprite preload and file writing, the export-only strings and the file-name assertion are gone, and the README lines no longer mention it. The rendering test still draws the card in every language and scope, since that covers the view itself.

Rebased on main as well (one trivial conflict next to the multi-account settings in UsageStore). scripts/test-gate.sh: 1289 tests, 0 failures, logic-core coverage 94.20%.

[chattymin]

Thank you for your contribution!