feat: add usable Bible version filters

[cameronapak]

Implements YPE-4657: apps can limit which Bible versions the SDK uses.

Public API

• permittedVersionIds, excludedVersionIds, permittedLanguageTags on YouVersionProvider (and YouVersionPlatformConfiguration for core-only hosts)
• Unset = no restriction. Empty permit list = permit nothing. Allowlists AND. Exclusion wins.

Refuse

• An unusable id is not a Bible version this app may use — lists, picker, recents, reader/card/text/VOTD, core/hooks
• Core throws Error with status: 403 before returning scripture (no network when the id alone decides)
• UI reuses forbiddenError. One dev console.warn for a host-passed unusable versionId
• No silent fallback to 3034. No picker-as-escape-hatch

Lists

• Filtered getVersions / getLanguages walk server pages so a usable row on a later page is not dropped
• page_size: '*' still walks every server page when filter field injection exceeds the API's 3-field * cap
• Picker recents are hidden at read time; localStorage is not rewritten

Docs: CONTEXT.md, docs/adr/YPE-4657-usable-bible-version.md, package READMEs.

  

Greptile Summary

The PR adds app-configurable Bible-version and language filters across core, hooks, and UI.

• Enforces allowlists and exclusions before scripture and highlight operations.
• Filters version and language collections while preserving pagination overflow.
• Propagates filter configuration through providers and hides unusable picker entries and recents.
• Adds tests, documentation, and package changesets for the public API.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/core/src/version-filters.ts	Implements filter predicates and resumable filtered pagination; the stable-page overflow fix preserves all usable rows.
packages/core/src/languages.ts	Preserves logical all-page collection while omitting the incompatible wire-level page_size parameter when filter fields are injected.
packages/core/src/bible.ts	Applies version policy to collection and content APIs, including metadata checks for language-based restrictions.
packages/core/src/highlights.ts	Enforces the same usable-version policy before highlight reads, writes, and deletes.
packages/hooks/src/context/YouVersionProvider.tsx	Synchronizes provider filter props to core configuration before descendants can fetch.
packages/ui/src/components/YouVersionProvider.tsx	Propagates filter configuration through the UI provider and bundled core boundary.
packages/ui/src/components/bible-version-picker.tsx	Applies version restrictions to picker results and restored recent selections.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Host[Host application] --> Provider[YouVersionProvider filters]
  Provider --> Config[Platform configuration]
  Config --> Core[Core version checks]
  Core --> Lists[Filtered versions and languages]
  Core --> Content[Scripture and highlight requests]
  Lists --> UI[Picker and recents]
  Content -->|Usable| API[Platform API]
  Content -->|Unusable| Forbidden[403 forbidden error]

Loading

_{Reviews (9): Last reviewed commit: "fix: give vapor-flash tests headroom pas..." | Re-trigger Greptile}

[changeset-bot]

🦋 Changeset detected

Latest commit: 73b6bc3

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

[cameronapak]

@greptile review

Code Implementor, sent on behalf of Cam. I am AI.

The last open thread is resolved. The catalog does not change order during pagination. Please post a new review so the official score matches the 5/5 you already agreed on that thread.

[Dustin-Kelley]

🙌