Project-SDE-WP-Suite/docs/waves/wave-4.md

# Wave 4 — Platform prerequisites

**Items:** `B4`, `S3`, `S2`, `B5`, `S10`, `S11`, `S12`, part of `C4`
**Depends on:** wave 3 merged
**Why here:** `X1` and `X5` are blocking dependencies that resolve in this wave. Two of the
most valuable field requests — the QA gate (`CR-014`) and the kitting notification
(`CR-011`) — promise emails containing a direct link to a work package. Nothing in this app
has a URL. Until `T4.2` lands, those emails cannot be built.

`T4.5` through `T4.7` are small and could be done any time. They are here because every
component built in waves 5 through 8 inherits them, and retrofitting is what `C1` warns
about.

---

### T4.1 — B4: Server aggregates replace localStorage-derived counts

- **Items:** `B4`
- **Depends on:** T3.2
- **Blocks:** T5.3, T6.3, T6.5
- **Surface:** `server/` + `html/`
- **Files:** server API, launcher, creator dashboard

**Problem:** Launcher SOP status reads `localStorage`, and the creator's dashboard carries a
comment admitting it reads local data and wires to SQL in Phase 2. Per-browser numbers that
look authoritative are worse than no numbers: two people looking at the same project see
different counts and neither is told.

**Do:** Add server endpoints returning the aggregate counts the launcher and dashboard need,
computed from the database. Point both surfaces at them. Delete the `localStorage` reads for
anything presented as a count or a status rollup.

Design the aggregate shape to support grouping by building, floor and sector, because
`CR-018` needs exactly that in wave 6. You do not have to expose the grouping yet, but do not
build a shape that cannot.

**Do not:** leave a `localStorage` fallback for counts. A silently-stale fallback is the
failure mode being fixed. If the endpoint fails, show an error state.

**Done when:**

- [ ] launcher and dashboard counts come from the server
- [ ] two different browsers signed in as different users show identical counts for the same project
- [ ] no `localStorage` read remains behind any displayed count; grep confirms
- [ ] endpoint failure shows an explicit error state, not a zero and not a stale number
- [ ] the aggregate response can be grouped by location without a schema change

---

### T4.2 — S3: URL state

- **Items:** `S3`, part of `C4`
- **Depends on:** T2.2
- **Blocks:** T7.6, T8.3 (blocking dependency `X1`)
- **Surface:** `html/`
- **Files:** all 6 pages, routing/state handling

**Problem:** No `pushState` anywhere. Tab switches, dashboard views and package selections
change no URL. You cannot send someone a link to WP07, and a refresh loses your place.

**Do:** Give addressable state a URL. At minimum: the selected project, the selected work
package, the active tab or section, and the active dashboard view or filter. Restore state
from the URL on load. Make browser back and forward behave.

Deep links must work for a signed-out user: land on login, then continue to the requested
target after signing in. An email link that dumps the recipient on a dashboard is the
failure this task exists to prevent.

**Do not:** use hash-only routing if the server can serve paths. Do not put anything secret
in the URL.

**Done when:**

- [ ] a URL identifying a specific work package opens that work package directly
- [ ] the same URL works for a signed-out user via login, landing on the requested target
- [ ] refresh preserves project, package, tab and view
- [ ] browser back and forward move through states without a full reload or a broken view
- [ ] copying the URL and opening it in a second browser reaches the same view
- [ ] `pushState` count is greater than 0; record the new count

---

### T4.3 — S2: Autosave and unsaved-work guard

- **Items:** `S2`, part of `C4`
- **Depends on:** T4.2
- **Blocks:** T7.7 (blocking dependency `X8`)
- **Surface:** `server/` + `html/`
- **Files:** creator, SOP wizard, `work-package-suite-app.js:326`

**Problem:** No autosave and no unsaved-work guard. The only `beforeunload` listener is
analytics dwell tracking. On a form roughly 4,700px tall, a mis-click loses everything.

**Do:** Autosave drafts on a debounce and on step or section change. Add a real
`beforeunload` guard for genuinely unsaved changes, alongside the analytics listener rather
than replacing it. Add draft recovery: if a session ends with unsaved work, offer it back on
return.

**Do not:** fire the guard when nothing has changed. A dialog that appears on every exit
gets clicked through and is worse than none.

**Done when:**

- [ ] typing then navigating away and returning restores the work
- [ ] typing then closing the tab prompts; not typing then closing does not
- [ ] autosave survives a browser crash simulation (kill the tab, reopen)
- [ ] the analytics dwell listener still functions
- [ ] autosave failure is surfaced to the user, not swallowed

---

### T4.4 — B5: Honest save status

- **Items:** `B5`
- **Depends on:** T4.3
- **Blocks:** nothing
- **Surface:** `html/`
- **Files:** creator, SOP wizard, existing toast system

**Problem:** An "All changes saved" toast already appears, but it belongs to the sync outbox,
not the draft. The app already implies a promise it does not keep.

**Do:** A persistent save-state indicator tied to the actual draft: saving, saved with a
timestamp, or failed with a retry. Distinguish it clearly from the sync outbox message, or
rename the outbox message so the two are not confused.

**Done when:**

- [ ] the indicator reflects real draft state, verified by watching it during a save failure
- [ ] a failed save is visually distinct from a successful one and offers a retry
- [ ] the sync outbox message no longer reads as a draft-save confirmation
- [ ] the indicator is announced via `aria-live` (see `T4.5`)

---

### T4.5 — S10: `aria-live` regions

- **Items:** `S10`
- **Depends on:** T3.2
- **Blocks:** nothing, but every later task depends on the pattern existing
- **Surface:** `html/`
- **Files:** both toast systems, admin banners, `login.html` as the reference

**Problem:** Zero `aria-live` regions app-wide. Both toast systems and every admin banner
announce nothing. `login.html` already does this correctly with `role="alert"` and
`role="status"`; the pattern never spread.

**Do:** Copy the `login.html` pattern into both toast systems and the admin banners. Errors
use `role="alert"` (assertive), confirmations use `role="status"` (polite).

**Done when:**

- [ ] every toast and banner announces
- [ ] errors interrupt, confirmations do not
- [ ] verified with a screen reader, or with an automated check plus a manual read of the markup
- [ ] `aria-live` region count is greater than 0; record it

---

### T4.6 — S11: Helper text contrast

- **Items:** `S11`
- **Depends on:** T3.2
- **Blocks:** nothing
- **Surface:** `html/`
- **Files:** canonical tokens, `console.css:85-87` as the reference

**Problem:** `--text-dim: #8d8d8d` at 12px is about 2.9:1. `console.css:85-87` already
diagnosed and fixed this; the other two sheets did not follow. Now that tokens are
consolidated, fix it once.

**Do:** Raise the dim-text token to meet 4.5:1 against its actual backgrounds. Check it on
every surface it lands on, including shaded cards and table rows, not just white.

**Done when:**

- [ ] all helper and hint text measures at least 4.5:1 against its real background
- [ ] the fix lives in the canonical token, not per-sheet
- [ ] `console.css` no longer needs its local override; remove it
- [ ] measured values are recorded in the PR

---

### T4.7 — S12: Restore the focus ring

- **Items:** `S12`
- **Depends on:** T3.2
- **Blocks:** nothing
- **Surface:** `html/`
- **Files:** `work-package-suite-styles.css:322-328`

**Problem:** `outline: none` plus a pale 3px glow. Keyboard users cannot see where they are.

**Do:** A visible focus indicator meeting at least 3:1 against adjacent colors, applied
consistently to every interactive element. Use `:focus-visible` so mouse users do not see
rings on click.

**Do not:** ship `outline: none` without a replacement anywhere in the app.

**Done when:**

- [ ] tabbing through every page shows a clearly visible indicator at each stop
- [ ] the indicator meets 3:1 against adjacent colors on every background it appears on
- [ ] no `outline: none` remains without an accompanying visible replacement; grep confirms
- [ ] mouse clicks do not leave a persistent ring

---

## Wave 4 exit criteria

- [ ] counts come from the server and match across browsers
- [ ] work packages are addressable by URL, including from a signed-out state
- [ ] drafts autosave and unsaved work is guarded
- [ ] toasts announce, helper text is legible, focus is visible
- [ ] `X1` and `X5` are cleared, unblocking `CR-011`, `CR-014`, `CR-004` and `CR-018`