Files
Project-SDE-WP-Suite/docs/waves/wave-14.md
Matt Mabrey 40827d5371 T14.2 (D27): the offline sign-in window follows the server
/api/auth/me returns session_expires_at (the session token exp, UTC). The browser
keeps it and never extends it: the fixed 12 hours and the sliding reset are gone.
Offline before that time the app opens as normal. Offline after it the app opens in
read-and-queue mode: no redirect, one mode line, changes are queued and held until
a page load gets a good answer from the server. wpCacheAuth refreshes the cached
user without moving the end time.

D26 and D27 recorded as Accepted. tests/session_expiry_check.py (22 checks) fails
against the old 12 hour rule.
2026-10-17 14:18:53 -07:00

13 KiB

Wave 14: The outbox keeps every change, and the sign-in limit cannot destroy it

Items: D26, D27, BL-061 (B5 is context only: its wording rules stay, and this wave does not widen it) Depends on: wave 13 merged (it is, except T13.1). Independent of wave 15. Decision record: docs/waves/decisions-2026-10-17.md (D26 and D27 are accepted as of 2026-10-17, see "Open questions") Unblocks: T13.1 (idle timeout). T13.1 must not reach main before T14.1 and T14.2 are done. Branch rule: one task for each pull request. Cut each branch from main.

Why this wave exists

The outbox in html/project-data.js queues each save in localStorage and sends it later. A crew in the field can work with no signal, and the changes go out when the network returns. The code was checked on 2026-10-17 against the 8 hour session limit (D25) and the idle timeout that T13.1 adds. It has four faults that lose or hide work. They are small now. The idle timeout would make them common.

# Fault Where Result
1 A 401 (session ended) or 403 is treated like any other 4xx. The change is marked dead and is never sent again. project-data.js, flush() A crew that works past the session limit, or past an idle timeout, comes back online and every queued change is rejected for good. The badge says "rejected by the project". The change is not lost from the device, but nothing can send it.
2 qWrite() swallows a storage error. project-data.js, qWrite() If the device storage is full, a change is not queued and nobody is told.
3 The queue belongs to the browser, not to a person. A queued change has no owner. project-data.js, enqueue() On a shared device, person B signs in and the queue of person A is sent under the name of person B.
4 The offline sign-in window is a fixed 12 hours in the browser. auth-guard.js, around line 183 It does not follow AUTH_SESSION_HOURS (8 since D25). It also slides: every online page load resets it. The browser and the server disagree about when the session ends.

Also: the sync badge sits over page controls (BL-061) and cannot be used with a keyboard or a finger. The badge is a div with pointer-events:none. A badge that must ask a person to sign in again needs a real link or button.

Rules for this wave

  • Do not use a div with onclick (CLAUDE.md, accessibility). The sign-in action is an <a> or a <button>.
  • Status text goes in an aria-live region. The badge already has role="status". Keep it.
  • Server work is needed for T14.2 (one new field). Do not store session data in localStorage as the source of truth.
  • Colors, spacing and type come from the shared tokens. Do not add a raw hex value to a page stylesheet.
  • Frontend checks: run the app on a throwaway SQLite database, check at 390 px and 1440 px, capture before and after screenshots, run the smoke test (use http://127.0.0.1, see BL-071).
  • Do not fix other problems you see. Log them in docs/waves/backlog.md.

T14.1: D26 a sign-in problem never destroys a queued change

  • Items: D26
  • Depends on: nothing (first task)
  • Blocks: T14.2, T14.3, T13.1
  • Surface: html/
  • Files: html/project-data.js, html/auth-guard.js, a new tests/outbox_check.py

Do:

  1. In flush(), treat 401 as held, not dead. Stop the run. Do not add to tries. Do not mark any change dead. Keep the whole queue in its order. Set a "held for sign-in" state that the badge can read through ProjectData.syncStatus() (add a field, for example held: true).
  2. Keep 403 as a permanent refusal, but say why in the reason text ("you no longer have access to this project"). Keep 409 (archived project) and the other 4xx as they are.
  3. When the person signs in again (the page loads with a good session, or wp-auth-ready fires), clear the held state and flush at once. The online event, the 20 second timer and the tab-focus trigger must not clear it early: a held queue sends only after a good session check.
  4. Make qWrite() return true or false. If it fails, enqueue() must tell the caller and raise the device full state. The change stays in the page memory and the form stays open. The badge says the change is not saved on this device. Do not drop it silently.
  5. Give each queued change an owner (the signed-in username) when it is queued. At flush time, if WP_USER is not the owner, hold that change and name the owner in the message. Do not send it. Do not discard it. (See open question 1.)
  6. Make sure auth-guard.js does not delete the queue when it sends a person to login.html after a 401. It must keep wp_sync_outbox_v1.

Done when:

  • a queue of N changes meets a 401: all N are still in the queue, none is dead, tries did not change, and the badge state is "held"
  • after a good sign-in, all N changes reach the server in their original order, and the queue is empty
  • a 403 marks only that change dead, with a reason that names the cause
  • a full device store (a forced QuotaExceededError) is reported to the caller and the badge. No change disappears silently
  • a change queued by person A is not sent when person B is signed in; it is sent after A signs in
  • tests/outbox_check.py covers each case above and fails when flush() is put back to the old rule (a mutation check)
  • the full suite passes (2026-10-17: 52 of 54 checks pass; the 2 others are generalinfo_check and token_check, known and not regressions). mobile_check covers 390 px. No before and after screenshots were taken: the badge looks the same until T14.3. The badge words for the new states are plain text. T14.3 gives them their final wording and the Sign in control.

Built (2026-10-17): commit 73f0b5e. Open question 1 as accepted: another person's changes are held and the badge names the owner. A change queued before the sign-in check finished has no owner and can be sent by anyone, as before.


T14.2: D27 the offline sign-in window follows the server

  • Items: D27
  • Depends on: T14.1
  • Blocks: T13.1
  • Surface: server/ and html/
  • Files: server/app.py (whoami()), html/auth-guard.js, html/wp-format.js (line 223 writes the cache), tests

Do:

  1. Add one field to /api/auth/me: session_expires_at (the exp claim of the session, as a UTC time). Read the claim from the token that get_current_user already validated. Do not add a database column. When T13.1 lands, this field is the current exp and moves with each refresh.
  2. In auth-guard.js, store session_expires_at in wp_auth_cache. Replace the fixed 12 * 3600 * 1000 with a rule that uses it. The rule for this wave (see open question 2):
    • offline, the app opens while the current time is before session_expires_at;
    • after that time, offline, the app still opens in a read and queue mode: the person can see cached data and add changes, which go to the outbox and are held (T14.1) until a good sign-in. The app does not go to login.html while it has no network, because that page cannot load an Okta sign-in without a network;
    • online, a 401 goes to login.html as now, and the outbox is kept (T14.1).
  3. Stop sliding the window. A page load must not extend wp_auth_cache. Only the server can extend a session.
  4. Show the person which mode they are in. One line: "Working offline. Sign in again when you have a signal to send your changes." Use the same aria-live region as the badge.

Done when:

  • /api/auth/me returns session_expires_at, and it matches the token (tests/session_expiry_check.py, no database change)
  • the fixed 12 hours is gone from auth-guard.js
  • opening the app offline before the time works; opening it offline after the time gives read-and-queue mode and does not redirect
  • online with a dead session: redirect to login.html?next=..., queue kept, changes sent after sign-in (the send after sign-in is the T14.1 test, section 3)
  • a page load does not extend the cached window
  • the mode line is announced by a screen reader (aria-live) and fits at 390 px. The line is in the badge, which has role="status" (checked). It is not checked at 390 px or with a real screen reader. Do this in T14.3, which rebuilds the badge.

Built (2026-10-17): tests/session_expiry_check.py (22 checks) fails when the old 12 hour rule is put back (7 failures). The mode line shows only in read-and-queue mode, not when the app opens offline before the session ends, because "sign in again" would be wrong while the session is still good. In read-and-queue mode the outbox does not send at all until a page load gets a good answer from the server. Saving display preferences refreshes the cached user and keeps the end time (wpCacheAuth).


T14.3: D26 and BL-061 the sync badge shows the true state and gets out of the way

  • Items: D26, BL-061
  • Depends on: T14.1
  • Blocks: nothing
  • Surface: html/
  • Files: html/project-data.js (renderSyncBadge), html/wp-chrome.css or the shared token file, tests/a11y_check.py, tests/autosave_check.py (it reads the badge strings)

Do:

  1. Show these states, each with its own words that name the project, never a draft save (the B5 rule that wave 4 set): sending, retrying, held for sign-in (with a link or button "Sign in"), not saved on this device (store full), rejected (with the reason), and all sent (hides after a short time).
  2. Make the badge usable: the "Sign in" and "Dismiss" controls are <a> or <button> elements with a visible focus ring and a touch target of at least 44 px. Remove pointer-events:none for the states that have controls.
  3. Keep the badge clear of page controls (BL-061): do not show it on pages that have no outbox work (the console pages), and place it so that it does not cover the bottom-right action buttons at 390 px or 1440 px.
  4. Keep text contrast at 4.5:1 or better in every state.
  5. Update the tests that read the badge text (autosave_check.py reads its symbols; a11y_check.py reads the element).

Done when:

  • each state shows in a browser test, with its text, at 390 px and 1440 px
  • "Sign in" works with the keyboard and by touch, and goes to login.html?next=...
  • the badge covers no control on the User Directory at 1440 px or the bulk bar at 390 px (the two places BL-061 named)
  • no badge on the console pages
  • the contrast check passes for every state
  • autosave_check.py and a11y_check.py pass

T14.4: verify the wave and release T13.1

  • Items: D26, D27, BL-061, T13.1
  • Depends on: T14.1, T14.2, T14.3
  • Blocks: nothing

Do: Run the full suite, the smoke test and seed_demo.py. Then test the real case by hand on a phone or tablet: sign in, set the device to airplane mode, make three changes in Field View, wait until the session limit has passed (use AUTH_SESSION_HOURS=1 on a test stack with a clock change, or a forced expiry), turn the network on, and check that the badge shows "held for sign-in", that signing in sends all three, and that the server has them. Then rebase feat/waves-11-13 T13.1 (6cde6e3) onto main, run tests/session_idle_check.py and the same hand test with the idle timeout on, and merge T13.1 as its own pull request.

Done when:

  • the hand test passes on one iPhone and one Android device (or the failure and the reason are written here)
  • the full suite and the smoke test pass on the final tree
  • T13.1 is on main, and tests/session_idle_check.py runs (it no longer skips)
  • the wave 13 exit line about D18 is ticked

Open questions

Answered 2026-10-17 (Matt accepted the proposal for questions 1, 2 and 3). Question 4 is still open and belongs to T13.1.

  1. Shared devices. If person B signs in on a device that holds unsent changes from person A, what must happen? Proposed: hold A's changes, name A in the badge, send them when A signs in. Do not send them as B and do not discard them. Other choices: allow B to discard A's changes after a confirmation; or send them as B (not proposed, wrong author in the log).
  2. Offline window. Proposed for this wave: the app opens offline until the session ends, and after that works in read-and-queue mode. The 7 day offline window (BL-062, Q2) is a later wave. Do you accept this order, or must 7 days come first?
  3. Device full. Proposed: do not drop the change, keep it in the page memory, and tell the person. Is "tell the person and keep the form open" enough, or must the app also stop new edits?
  4. Idle time. T13.1 proposes 30 minutes. It is a proposed value, not a decision. It matters here because every minute of idle time offline ends the session on the server side.

Wave 14 exit criteria

  • a session that ends while changes are queued loses none of them
  • a full device store is never silent
  • a change is sent only under the signed-in person who made it
  • the offline window follows the server (no fixed 12 hours in the browser)
  • the badge shows the true state, is usable, and covers no control
  • T13.1 is merged to main and D18 is fully accounted for