[Feature Branch] Implement Highlights on the React Native Expo SDK 🖍️

[cameronapak]

Work in progress feature branch

Greptile Summary

The PR introduces native Highlights support across core auth, optimistic persistence and queue draining, permission handling, and the native Bible reader.

• Adds cached and optimistic highlight reads and writes with offline queue processing.
• Adds permission-grant and token-access APIs to the authentication layer.
• Adds native verse actions, consent and sign-in prompts, and sign-out protection for queued highlights.
• Updates package dependencies, documentation, localization assets, and the example application.

Confidence Score: 4/5  · 

The PR is not yet safe to merge because authenticated users whose token has no associated user ID still cannot apply or remove highlights.

The current write entry point rejects a null user ID as signed out before checking the valid token, and the test suite explicitly preserves this behavior for an authenticated session with an access token.

Files Needing Attention: packages/core/src/highlights/use-highlights.ts

Important Files Changed

Filename	Overview
packages/core/src/highlights/use-highlights.ts	Implements cached fetching and optimistic highlight writes, but the previously reported authenticated-without-user-ID rejection remains.
packages/core/src/highlights/queue.ts	Adds per-user, per-scope persistence for offline highlight writes.
packages/core/src/highlights/drain.ts	Adds background retry and reconciliation for persisted highlight writes.
packages/core/src/auth/auth-provider.tsx	Adds permission state, token access, single-flight refresh behavior, and highlight cleanup integration.
packages/ui/src/native/bible-reader.tsx	Integrates controlled highlights, native verse actions, permission prompts, and queued-write-aware sign-out confirmation.
packages/ui/src/native/bible-verse-action-sheet.tsx	Adds native highlight, copy, share, and selection actions for the Bible reader.

Sequence Diagram

sequenceDiagram
  participant User
  participant Reader as Native BibleReader
  participant Flow as Highlight Permission Flow
  participant Hook as useHighlights
  participant Queue as Persistent Write Queue
  participant API as Highlights API

  User->>Reader: Select verse and color
  Reader->>Flow: apply(color, verses)
  Flow->>Flow: Check sign-in and permission
  Flow->>Hook: apply(color, verses)
  Hook->>Queue: Persist intended write
  Hook->>Reader: Paint optimistically
  Hook->>API: Send write
  alt Request succeeds
    API-->>Hook: Success
    Hook->>Queue: Remove queued entry
  else Network or server unavailable
    API-->>Hook: Transient failure
    Hook-->>Reader: Keep optimistic paint
    Queue->>API: Retry when drain wakes
  else Request refused
    API-->>Hook: Authorization or validation failure
    Hook->>Reader: Revert paint
  end

Loading

_{Reviews (2): Last reviewed commit: "test(core): align drain-host test with s..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Auth (PKCE OAuth, token storage, refresh)

[cameronapak]

Desired End State — locked for #100 / v1

Kody Bot on behalf of Cam. Summary from a reconciliation pass with Ticket Griller and Critique Researcher. Written with the simple-english skill.

Ship target

PR #100 is the ship target for Highlights v1 on the RN Expo SDK.

PR #104 is example-only. It will not merge.

In scope for #100

• AppState revalidation lands on this branch via PR feat(core): refresh highlights when app becomes active (YPE-4491) #129 (YPE-4491). It is not a fast-follow.
• Localization keys for consent, sign-out, and copy-share already exist in en.json on [Feature Branch] Implement Highlights on the React Native Expo SDK 🖍️ #100.

Out of scope for v1 (later follow-ups)

• Host tab or screen-focus refreshHighlights on BibleReader. Do not add a public partner handle for v1.
• Public onHighlightError. Do not add it for v1.
• Hung GET abort (AbortController / timeout) stays on YPE-4499. Offline write queuing does not fix hung reads. Brenden owns that work.

Architecture notes

Cuts between orchestrator and permission-flow layouts can differ. Those differences are not missing product pieces for Desired End State.

Swift check

The YouVersion Swift SDK on main has no AppState or foreground highlights refresh. It also has no partner refreshHighlights API. Chapter .task load, auth or permission forceReload, and a 5-minute throttle cover refresh there.

Bottom line

#100 matches Desired End State for v1 when #129 is in the stack. Keep YPE-4499 separate.

[cameronapak]

@greptile-apps, please review for production readiness of our Highlights feature on our React Native Expo SDK

[greptile-apps]

Too many files changed for review (137 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.

[cameronapak]

ADDRESSED AND FIXED

Four release-blocking findings from a review of this branch.

   **P0 — The write-queue drain un-paints a write when its forced refresh fails silently.**

   In `drain.ts`, `forcedToken()` calls `refreshNow()`. That call is `refreshToken({ force: true })`, and `refreshToken` never
   throws. It swallows a non-revoked failure into `setError` and leaves the old token in `accessTokenRef`. So the `catch` in
   `forcedToken` never runs.

   When the token is stale and the network is down, the drain sends the same stale token again. The server refuses it a second
   time. Then `revert()` drops the entry and un-paints the verse.

   This is the "silent un-paint of a real write" that ADR 0018 forbids. The fix: `forcedToken` must make sure that the refresh
   actually minted a new token before the retry. Use `getAccessToken()` for that. It reports `refresh-failed`. Take ordinary
   backoff, not revert, when the result is `refresh-failed`.

   **P1 — The permission flow and the reader sign-in gate ignore the loading window.**

   On a cold start with a stored session, `accessToken` starts `null`. `isLoading` is true. `apply()` branches on
   `current.isAuthenticated`, and `bible-reader.tsx` sets `needsSignIn` from `!auth.isAuthenticated`. Neither reads
   `isLoading`.

   A signed-in user who taps a swatch in that window sees a sign-in prompt. With a missing cached grant, OAuth opens. The write
    path already waits via `waitForAuthSettled()`. Gate both branches on `isLoading` too.

   **P1 — `@youversion/platform-core` version skew.**

   `packages/core` pins `platform-core@2.5.0`. `packages/ui` pins `platform-react-ui@2.6.2`, which pulls `platform-core@2.6.2`.
    Two copies resolve. The `Highlight` type crosses that boundary. Align the pins before release.

   **P1 — `expo-application` is misdocumented and missing from the example app.**

   `app-name.ts` imports `expo-application`, and the sign-in sheet calls it. `AGENTS.md` and the changeset say it is already a
   core dependency. That is false. Core neither imports nor declares it. Consumers who follow that note skip the install and
   rebuild, then see `Cannot find native module 'ExpoApplication'`. Add it to the example app and fix the docs.