deadhead-space-freight-tycoon/memory-bank/change-requests/CR-025-short-away-summary.md

# Change Request CR-025 — Short "While You Were Away" Summary

> **Numbering note (added when recorded):** this request arrived titled "CR-023 — Short 'While You Were Away' Summary" for "Phase 23". CR-023 (Shop Time Counts as Rest) and CR-024 (Fleet Sleep Mode), and Phases 23 and 24, already existed, so it is stored as **CR-025** and done as **Phase 25**: every "23.n" below means **25.n**. Its references map to this repo as: "Phase 13 and CR-001 through CR-022" = Phase 13 and **CR-001 to CR-024**; "CR-001 faster start" (scripted contract flavor messages) is the same number; "CR-011 local-first" = **CR-014** (the engine, the save, retention on save); "CR-014 leg fuel cost" = **CR-015** (fuel tanks: a leg's fuel at the tank's average price, decision 0.5.98); "CR-019 independent pilots" = **CR-021** (the per-pilot logbook, the NPC spending floor); "CR-022 fleet sleep" = **CR-024**. Plan 9.2 is the same step. Its new decisions CR-023.D1–D3 are recorded as **0.5.140 Highlights pop-up**, **0.5.141 Logbook screen** and **0.5.142 Net earnings**.
>
> **On recording:** "HQ" is the Bridge (the dashboard), as in CR-021 and CR-024.

**Project:** Deadhead: Space Freight Tycoon
**Applies to:** a build with Phase 13 and CR-001 through CR-022 complete
**Do this:** as **Phase 23**
**Related docs:** `change-request-faster-start.md` (CR-001), `change-request-local-first.md` (CR-011), `change-request-independent-pilots.md` (CR-019), `change-request-fleet-sleep.md` (CR-022), `DECISIONS.md`

This change request is written for the local-first engine (CR-011).

---

## 1. Why

The "while you were away" pop-up lists every delivery, and CR-019 added a full per-pilot logbook to it. With a handful of Independent pilots running for a day, it becomes a long scroll. The pop-up should show **highlights only**: company totals, anything that needs the player, and one line per pilot. Full detail moves to a separate **Logbook** screen.

## 2. The pop-up

Fits on one phone screen without scrolling, however many pilots there are.

### Layout, top to bottom

1. **Header:** "While you were away · 9 h 40 m"
2. **Sleep banner** (CR-022), if the fleet went quiet, with **Back to work**.
3. **Company totals**, one row of figures: net earned, deliveries, discoveries (if any), loan repaid (if any).
4. **Highlights**, at most 3, in this priority order:
   1. New location discovered
   2. Pilot leveled up ("Rosa reached level 4 · 1 skill point")
   3. Goal ready to claim
   4. Scripted contract flavor message (CR-001)
   5. Best single delivery ("Biggest job: Helium-3 Canisters to Earth, 8,420 cr, Rosa")
   6. Problem needing attention: a ship idle with no reachable jobs, fuel too low to fly, emergency fuel available, or credits below the NPC spending floor (CR-019)

   If there are more than 3, show the top 3 and "+2 more in the Logbook".

5. **Pilots**, one line each: name, deliveries, net profit, and where they are now ("Rosa · 6 jobs · +12,300 cr · Resting at Ceres"). A level-up adds a small badge.
   - Only pilots with activity during the absence are listed; others are summed in one line ("3 pilots had nothing to do").
   - Sorted by net profit, highest first.
   - At most **5 pilot lines**; the rest collapse into "+7 more pilots: +18,900 cr".
6. **Buttons:** **View logbook** and **Done**.

### Short absences

If the absence produced **3 events or fewer** in total (deliveries, discoveries, level-ups), show those events directly instead of the totals and pilot sections, so a quick check-in still reads naturally ("Courier delivered Mail & Parcels to the Moon, +410 cr").

### What counts as "net"

Payout minus pilot share, fuel used (CR-014 leg fuel cost), and loan repayment, matching the delivery summaries. Fuel bought counts when it's spent, not when it's bought.

## 3. The Logbook screen

- A new screen, reached from **View logbook** and from HQ.
- Holds the full detail CR-019 put in the pop-up: per pilot, every job (good, route, payout, pilot share, fuel), deadheads, refuels, rests, upgrades finished, XP gained.
- Filter by pilot and by time range ("This absence", "Last 24 h", "Last 7 days").
- Keeps entries for 7 days, pruned on save (CR-011 retention), so the save stays small.

## 4. Rules for this change

- All rules in `implementation-plan.md` §0.1 apply: steps in order, one commit per step, each step's test must pass.
- Building the summary (totals, highlights, pilot lines, collapse) is a pure function of the logbook entries for the absence, so it can be tested without UI.
- Highlight wording lives in content.
- Save migration: existing summary data is converted to logbook entries where possible; otherwise it's dropped.
- Update `architecture.md` and `progress.md` as you go. Stop for the user's review at the end of Phase 23.

## 5. Decisions

Record these in `DECISIONS.md` and `implementation-plan.md` §0.5, using the next free numbers (labeled CR-023.D1–D3 here; note the mapping).

- **CR-023.D1 Highlights pop-up.** Per §2: totals, at most 3 highlights, at most 5 pilot lines, one screen, with a direct list for absences of 3 events or fewer.
- **CR-023.D2 Logbook screen.** Full detail per §3, kept for 7 days.
- **CR-023.D3 Net earnings.** Payout minus pilot share, fuel used, and loan repayment.

## 6. Steps — Phase 23

### Step 23.1 — Engine: logbook entries and retention

- Store every relevant event (delivery, deadhead, refuel, rest, upgrade finished, discovery, level-up, goal ready) as a logbook entry with pilot, ship, time, and amounts. Prune entries older than 7 days on save.
- **Test:** Each event type creates one entry with the right fields. Entries older than 7 days are pruned; newer ones remain. Catch-up and live play produce the same entries.

### Step 23.2 — Sim: summary builder
- **Amended by CR-026:** Events are logbook entries; good ones and any that hurt a hull are highlights just below level-ups, and a short absence lists its trips' events (not counted towards the 3).

- A pure function that turns the entries for an absence into: duration, totals, up to 3 highlights in priority order with an overflow count, up to 5 pilot lines sorted by net profit with an overflow line, the idle-pilots line, and the "short absence" direct list when there are 3 events or fewer.
- **Test:** With 50 pilots' worth of entries, the result has exactly 5 pilot lines and an overflow line whose totals equal the rest. Highlights follow the priority order and cap at 3 with the right overflow count. Totals equal the sum of entries. With 2 events, the result is the direct list. Net matches the delivery-summary calculation.

### Step 23.3 — Client: highlights pop-up

- Replace the current pop-up with the §2 layout. Keep the CR-022 sleep banner and button.
- **Test:** Component tests: with 50 active pilots, the pop-up fits in a 375×667 viewport without scrolling; each section renders from a seeded summary; "+N more" lines appear only when needed; a short absence shows the direct list; Done dismisses it; View logbook opens the Logbook filtered to this absence.

### Step 23.4 — Client: Logbook screen

- Add the Logbook screen per §3, with pilot and time-range filters, reachable from the pop-up and from HQ.
- **Test:** Component tests: entries render per pilot with the CR-019 detail; filters narrow the list correctly; the "This absence" filter matches the pop-up's totals.

### Step 23.5 — Regression

- Run the full suite.
- **Test:** CI is green. Manual check: with several Independent pilots, leave the game for a few hours, reopen on a phone, and confirm the pop-up fits on one screen and the Logbook holds the full detail.

## 7. Amendments

| Where    | Change                                                                                  |
| -------- | --------------------------------------------------------------------------------------- |
| Plan 0.5 | Add CR-023.D1–D3.                                                                       |
| Plan 9.2 | "While you were away" becomes the highlights pop-up (23.3).                             |
| CR-019   | The per-pilot logbook moves from the pop-up to the Logbook screen (23.4).               |
| CR-022   | Sleep banner stays at the top of the pop-up.                                            |

## 8. Out of scope

Charts or graphs of earnings, exporting the logbook, per-pilot notification digests, and anything else in `implementation-plan.md` §0.3.