Final wiring of all things highlights API and auth-guard, with fix for highlight not deleting immediately (visually)

[cameronapak]

PLZ WATCH VIDEO ▶️

Summary

Server-backed BibleReader highlights go live: the dark-launch flag flips on after a final round of auth hardening, a fix for successful deletes being misread as failures, and Swift-parity UX corrections. Last PR of the YPE-1034 stack (#283 → #285 → #286 → this one); the consolidated changelog announces the launch and the removal of the accidentally shipped localStorage-only highlights.

Changes

1. Highlights are enabled by default (HIGHLIGHTS_LIVE on) — signed-in readers' highlights persist to their YouVersion account; six stacked changesets are consolidated into one launch changelog.

2. Removing a highlight no longer flashes back before disappearing — the core ApiClient treated empty-body 2xx JSON responses (the real DELETE shape) as failures, so the machine reverted the successful removal; regression tests now drive the real client through a stubbed fetch.

3. A data-exchange grant only applies to the user who initiated it — initiator recorded at redirect, read-and-cleared at callback, any mismatch fails closed; signIn also clears stale permission stashes so an abandoned flow can't leak grants across users.

4. A resumed pending write that fails 401/403 re-prompts for permission instead of silently reverting the reader's tap.

5. Sign-in matches the Swift SDK: appName / signInPromptMessage props, Platform wordmark, comma-joined requested_permissions wire format, and a permission cache seeded from token scope so a highlight tap doesn't re-prompt right after OAuth.

6. Dark mode matches the Swift SDK: highlight fills render at 0.3 opacity (1.0 in light mode), verse numbers paint white over dark-mode fills, and popover swatches preview the dimmed color a highlight will actually apply; fills also get subtly rounded corners with per-line-fragment rounding at wraps (deliberate web-native divergence from Swift's square fills); the active swatch shows a checkmark instead of an X.

7. Hardening and cleanup: xstate pinned to exactly 5.32.4 (supply-chain cooldown), review findings across all three packages (color row gated on interactivity, stable serverColors/refetch identities, shared useApiClient), the logo's accessible label is a required localized prop, the pending-permissions stash stores string[], and personal workflow notes are stripped from AGENTS.md.

8. One-shot sign-in grants survive the server's URL encoding: parseGrantedPermissions now also accepts bracket-array keys (granted_permissions[], indexed forms) that the auth server emits, on both the sign-in callback and the data-exchange return — previously the echoed grant was silently discarded and the permission dialog re-prompted after a successful sign-in.

9. StrictMode-proof auth: the OAuth code exchange and the token refresh are each shared across concurrent invocations, so a duplicate's 4xx can no longer clear the session or the just-seeded grants (previously the demo's <StrictMode> double-invoke could wipe a fresh sign-in or grant cache).

10. One-shot sign-in survives a silent server: a live instrumented capture (2026-07-23) showed the web callback carries no granted_permissions echo on either hop and the token scope is profile openid only — the SDK had zero evidence of the consent the user just gave. The permissions requested at signIn are now stashed (state-bound, fail-closed) and optimistically seeded as granted on a successful exchange; an over-optimistic seed self-corrects through the existing 401/403 → permission re-prompt path. The durable fix is server-side (echo the grant on the web callback) and is being filed with Platform.

11. Verse-number labels and footnote icons inherit the verse text color over highlight fills in both themes, so saturated light-mode fills no longer clash with muted gray glyphs (deliberate divergence from Swift, which only recolors the label in dark mode).

12. Reviewer simplification pass applied in full (12 comments, −286 lines: shared highlight test fixtures, dead helper/config removal, duplicate test deleted) and getHttpStatus now recognizes plain {status} objects, not just Error instances.

13. Mobile: the verse-action popover caps at the viewport width (with live tracking across mid-open resizes) and the swatch row scrolls horizontally with edge fades that appear only where content is hidden; Copy/Share stay pinned. Verified live at 300px.

14. Fill opacity churn, net zero: a same-day design decision briefly moved light-mode fills to 30% opacity and was then walked back — final state is the original 1.0 light / 0.3 dark (Swift parity). Kept in history as commits cf6a291/959f2ca and revert 7b91105.

Start here: change 3 — auth-boundary logic; the fail-closed path is the part worth adversarial review.

Test plan

• pnpm build && pnpm typecheck && pnpm lint && pnpm test: all green (1014 tests — core 369 / hooks 289 / ui 356)
• Vapor regression suite fails on the reverted fix, passes with it (fetch-stub end-to-end through the real client, machine, and adapter)
• Storybook integration tests run in CI

Needs manual check: one live confirmation in the vite demo — remove a highlight while signed in and confirm no flash. The one-shot flow's root cause was pinned down via a breadcrumb-instrumented live run (server returns no grant evidence; see change 10) and the fix is regression-tested against that exact captured shape. Live-verified 2026-07-23: signed-out tap → sign-in → OAuth → highlight applies with no second dialog.

Greptile Summary

This is the final PR in the YPE-1034 stack, flipping server-backed BibleReader highlights to live. It ships a substantial auth hardening pass alongside the feature launch: the empty-body DELETE flash fix, StrictMode-safe code-exchange and token-refresh deduplication, initiator-bound data-exchange grant safety, bracket-array permission parsing, and optimistic permission seeding for the web flow's missing server grant echo.

• Auth boundary (change 3 + 9): the data-exchange initiator is recorded before the redirect and cleared on return; any user mismatch or missing initiator fails closed. Code-exchange and token-refresh deduplication prevent StrictMode double-invocations from clearing tokens the winning run just seeded.
• DELETE flash fix (change 2): ApiClient now reads the response body as text first and treats an empty body as "no data", so a 200 application/json with no payload no longer throws and surfaces a successful delete as a failure.
• Permission seeding (changes 8 + 10): parseGrantedPermissions accepts bracket-array keys (granted_permissions[], granted_permissions[0]), and requested permissions are optimistically seeded on callback (state-bound, self-correcting via 401/403 → re-prompt) to work around the server returning no grant echo on the web flow.

Confidence Score: 4/5

Safe to merge except for the light-mode fill opacity constant, which doesn't match the product decision documented in the PR description.

The auth hardening, DELETE flash fix, and StrictMode deduplication are all well-designed and regression-tested. The one concrete gap is that HIGHLIGHT_FILL_OPACITY_LIGHT is still 1.0 even though the PR description's product decision (item 14) explicitly changed light mode to 30% — matching dark mode — and says swatches should preview the dimmed fill in both modes. The ADR update was written before that decision landed and still documents the pre-decision split. Everything else in the 63-file change looks correct.

packages/ui/src/components/verse.tsx (fill opacity constant) and packages/ui/src/components/verse-action-popover.tsx (swatch preview in light mode)

Important Files Changed

Filename	Overview
packages/core/src/Users.ts	Major auth hardening: StrictMode-safe code-exchange deduplication, state-bound permission stashes, optimistic permission seeding with self-correcting 401/403 path, and stale-stash cleanup at signIn start. Well-structured and test-covered.
packages/core/src/data-exchange.ts	Initiator-bound grant safety: initiator is recorded at redirect start, read-and-cleared on return, and any mismatch (different user, missing initiator) degrades to failure. Security design is solid and regression-tested.
packages/core/src/client.ts	Adds getHttpStatus with duck-type check (accepts any object with a numeric status property, not just Error instances), and fixes empty-body 2xx handling so DELETE responses no longer surface as JSON parse failures.
packages/core/src/permissions.ts	Adds bracket-array key support (granted_permissions[], granted_permissions[0]) via regex to handle PHP/Rails server encoding; extracts parsePermissionList for token-scope parsing. Correctly handles all observed server formats.
packages/ui/src/components/bible-reader-highlights-machine.ts	Removes the reprompt field from WriteOp — all apply-kind writes (user-initiated and resume-applied) now re-prompt on 401/403, fixing silent drop of resumed taps. Adds signedOut guard to auto-dismiss the permission dialog on sign-out.
packages/ui/src/components/verse.tsx	Introduces theme-aware fill opacity constants (1.0 light / 0.3 dark), but HIGHLIGHT_FILL_OPACITY_LIGHT = 1.0 contradicts the PR description's stated product decision that both modes should render at 30%.
packages/core/src/YouVersionPlatformConfiguration.ts	Adds dataExchangeInitiator storage (save/get/clear) and wires clearDataExchangeInitiator into clearAuthTokens so a sign-out always drops a pending initiator.
packages/hooks/src/internal/useApiClient.ts	New shared hook that centralizes ApiClient construction for all per-service hooks, reducing duplication. Optional mode ({ optional: true }) returns null instead of throwing for auth-tolerant callers.
packages/hooks/src/useApiData.ts	Adopts the useEvent-style fetchFnRef pattern to keep fetchFn out of fetchData's deps, stabilizing refetch identity across renders without stale-closure risk.
packages/ui/src/components/verse-action-popover.tsx	Adds horizontal scroll with per-edge fade masks (pure computeScrollFade function, ResizeObserver-tracked), viewport-width cap, corrected auto-focus on pointer-open, and theme-aware swatch previews.
packages/ui/src/components/use-bible-reader-highlights.ts	Adds highlightsInteractive flag and a reference-stable serverColors memoization (content-equality comparison via ref) to prevent spurious verse-style re-sweeps on no-op refetches.
packages/hooks/src/useHighlightAuthActions.ts	Saves the data-exchange initiator before the async token mint and clears it on error, ensuring any mid-await user change can't stamp the new session as the original initiator.

_{Reviews (14): Last reviewed commit: "revert(ui): restore full-strength light-..." | Re-trigger Greptile}

[changeset-bot]

🦋 Changeset detected

Latest commit: 7b91105

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-core	Minor
@youversion/platform-react-hooks	Minor
@youversion/platform-react-ui	Minor
vite-react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jaredhightower-youversion]

Simplification pass — a few candidates to delete or shrink; all non-blocking.

[jaredhightower-youversion]

LGTM!! Awesome job on this game. It's been a journey, but we've gotten to this point. I did watch the video. The small little nuances with the thing getting cut off: not sure if you were able to resolve that. If not, no worries. A small follow-up PR should be able to resolve that.

[Dustin-Kelley]

🔥