deadhead-space-freight-tycoon/memory-bank/change-requests/CR-028-live-toasts.md

# Change Request CR-028 — Live Toasts Instead of the Away Pop-up

> **Numbering note (added when recorded):** this request arrived titled "CR-026 — Live Toasts Instead of the Away Pop-up" for "Phase 26". CR-026 (Random Events) and CR-027 (Service Bookings), and Phases 26 and 27, already existed, so it is stored as **CR-028** and done as **Phase 28**: every "26.n" below means **28.n**. Its references map to this repo as: "Phase 13 and CR-001 through CR-025" = Phase 13 and **CR-001 to CR-027**; "CR-008 settings" = **CR-011**; "CR-011 local-first" = **CR-014**; "CR-019 independent pilots" = **CR-021**; "CR-022 fleet sleep" = **CR-024**; "CR-023 away summary" = **CR-025** (its "Step 23.2" = **Step 25.2**); "CR-024 random events" = **CR-026**; "CR-025 service bookings" = **CR-027**. Its decisions CR-026.D1–D4 are recorded as **0.5.160–0.5.163** (D1 = 0.5.160 … D4 = 0.5.163). "Plan 9.2" is the plan's Step 9.2 ("While you were away").
>
> **On recording:** "the HQ banner" for fleet sleep is the Bridge's "Fleet asleep" panel (CR-024, `FleetAsleep`). Today the pop-up opens on unacknowledged deliveries and finished upgrades and covers the absence since `player.awaySince`; per-entry "seen" replaces that as what opens it. Reduced motion is the Settings preference (CR-011) and the system setting.

**Project:** Deadhead: Space Freight Tycoon
**Applies to:** a build with Phase 13 and CR-001 through CR-025 complete
**Do this:** as **Phase 26**
**Related docs:** `change-request-settings.md` (CR-008), `change-request-local-first.md` (CR-011), `change-request-independent-pilots.md` (CR-019), `change-request-fleet-sleep.md` (CR-022), `change-request-away-summary.md` (CR-023), `change-request-random-events.md` (CR-024), `change-request-service-bookings.md` (CR-025), `DECISIONS.md`

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

---

## 1. Why

The "while you were away" pop-up appears even when the player has the game open and is watching. If Deadhead is on screen, things that happen should show as **small notifications that close on their own**. The pop-up is only for when the player comes back after the game wasn't on screen and something happened in the meantime.

## 2. Rules

### When is the player "here"?

- **Here:** the game's browser tab is visible (Page Visibility API), or the native app is in the foreground (Capacitor app state).
- **Away:** the tab is hidden or minimized, the app is in the background, or the game was closed.

### While the player is here: toasts

| Rule              | Detail                                                                                                                                                                                                         |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Position          | **Desktop** (viewport 768 px or wider): top-right corner. **Mobile:** top of the screen, centered, below the safe area.                                                                                        |
| Duration          | Closes on its own after **5 seconds**. Hovering (desktop) or touching (mobile) pauses the timer. Swipe or ✕ dismisses early.                                                                                    |
| Stacking          | At most **3** visible; newer push older down. Overflow becomes one "+N more" toast that opens the Logbook (CR-023).                                                                                           |
| Tapping           | Opens the related ship, pilot, location, or Logbook entry.                                                                                                                                                     |
| What gets a toast | Deliveries, discoveries, level-ups, goals ready, automatic events and radio-call outcomes (CR-024), service started and finished (CR-025), "waiting for funds" and "can't reach HQ" problems (CR-025).          |
| Batching          | Routine deliveries by Independent pilots within the same 10 seconds combine into one toast ("3 deliveries · +4,200 cr"). Player-dispatched deliveries, discoveries, level-ups, and problems always get their own toast. |
| Radio calls       | Unchanged from CR-024: a radio call opens its card and stays until answered or expired. It is never an auto-closing toast.                                                                                     |
| Fleet sleep       | If the fleet goes quiet while the player has the game open but hasn't made decisions (CR-022), show a toast and the HQ banner; no pop-up.                                                                      |
| Accessibility     | Toasts are announced politely to screen readers. With reduced motion (CR-008), they appear and disappear without sliding.                                                                                      |

Every event that gets a toast is marked **seen**.

### When the player comes back: the pop-up

- On returning from away (tab visible again, app back in the foreground, or a fresh launch), show the CR-023 "while you were away" pop-up **only if unseen events happened while away**.
- The pop-up covers exactly the unseen events from that away period; nothing that was already toasted.
- **Short trips away:** if the player was away for less than **60 seconds**, show any unseen events as toasts instead of the pop-up. A quick tab switch shouldn't trigger a full summary.
- If nothing happened while away, show nothing.

## 3. 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.
- "Seen" is per logbook entry (CR-023) and saved, so a reload doesn't re-show toasted events as a pop-up.
- The pop-up's content builder (CR-023 Step 23.2) takes the unseen entries for the away period instead of all entries since last open.
- Toast timing and the 60-second short-absence threshold live in the client config, not game content.
- Update `progress.md` after every step. Stop for the user's review at the end of Phase 26.

## 4. Decisions

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

- **CR-026.D1 Presence.** "Here" means the tab is visible or the app is in the foreground.
- **CR-026.D2 Toasts while here.** Per §2: top-right on desktop, top of the screen on mobile, 5-second auto-close, max 3, batched routine deliveries; radio calls keep their own card.
- **CR-026.D3 Pop-up only after being away,** and only for unseen events; under 60 seconds away uses toasts instead.
- **CR-026.D4 Seen tracking** per logbook entry, saved.

## 5. Steps — Phase 26

### Step 26.1 — Engine: seen tracking

- Add a "seen" flag to logbook entries and a command to mark entries seen (not a manual decision for CR-022). Save migration: all existing entries are marked seen.
- **Test:** New entries start unseen; marking them seen persists across reload; migrated saves have everything seen.

### Step 26.2 — Client: presence tracking

- Track here/away from the Page Visibility API (web) and Capacitor app state (native), recording when the player went away and came back.
- **Test:** Simulated visibility changes produce the right away start and end times; a cold start counts as returning from away since the last saved time.

### Step 26.3 — Client: toasts

- Build the toast system per §2: positions by viewport width, 5-second auto-close with pause on hover or touch, max 3 with "+N more", tap targets, batching of Independent deliveries, screen-reader announcements, reduced-motion behavior. Mark each toasted entry seen.
- **Test:** Component tests: at 1280 px wide toasts render top-right, at 375 px top-center below the safe area; a toast closes after 5 seconds and not while hovered; a fourth toast produces "+1 more"; three Independent deliveries within 10 seconds produce one combined toast; a discovery always gets its own; tapping opens the right screen; toasted entries are marked seen.

### Step 26.4 — Client: pop-up only after being away

- On return from away, if the away period was 60 seconds or more and unseen entries exist, show the CR-023 pop-up built from those entries and mark them seen when it closes. Under 60 seconds, show them as toasts. With no unseen entries, show nothing.
- Remove any path that opens the pop-up while the player is here.
- **Test:** With the game visible, a delivery produces a toast and no pop-up. Hiding the tab for 5 minutes during which two deliveries resolve, then returning, shows the pop-up with exactly those two. Hiding it for 30 seconds produces toasts, not the pop-up. Returning after an away period with nothing new shows nothing. Reloading after the pop-up closed doesn't show it again.

### Step 26.5 — Regression

- Run the full suite.
- **Test:** CI is green. Manual check on desktop and phone: keep the game open and watch deliveries arrive as toasts; switch away for a few minutes and confirm the pop-up summarizes only what happened while away.

## 6. Amendments

| Where           | Change                                                                       |
| --------------- | ---------------------------------------------------------------------------- |
| Plan 0.5        | Add CR-026.D1–D4.                                                            |
| Plan 9.2, CR-023 | The pop-up shows only after being away, for unseen events only.             |
| CR-022          | Sleep while the game is open shows a toast and HQ banner, not the pop-up.    |
| CR-024          | Event outcomes become toasts while the player is here; radio calls unchanged. |

## 7. Out of scope

A notification history panel beyond the Logbook, per-type toast settings, sounds, browser (system) notifications on web, and anything else in `implementation-plan.md` §0.3.