From 9706411290b9b9b3e16c98981fc285bd2bc1cc74 Mon Sep 17 00:00:00 2001 From: cameronapak Date: Tue, 6 Jan 2026 12:28:27 -0600 Subject: [PATCH 01/14] feat: add AGENTS.md and CLAUDE.md files for better AI and developer context --- AGENTS.md | 275 ++++++++------------------------------- packages/core/AGENTS.md | 36 +++++ packages/core/CLAUDE.md | 1 + packages/hooks/AGENTS.md | 27 ++++ packages/hooks/CLAUDE.md | 1 + packages/ui/AGENTS.md | 46 +++++++ packages/ui/CLAUDE.md | 1 + 7 files changed, 169 insertions(+), 218 deletions(-) create mode 100644 packages/core/AGENTS.md create mode 120000 packages/core/CLAUDE.md create mode 100644 packages/hooks/AGENTS.md create mode 120000 packages/hooks/CLAUDE.md create mode 100644 packages/ui/AGENTS.md create mode 120000 packages/ui/CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 2804b62..abbbb68 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,236 +1,75 @@ -One AGENTS.md works across many agents, such as GitHub Copilot, Roo Code, Open AI's Codex, Devin, and more. This is a README for agents to help AI coding agents work on this project. +# AGENTS.md -## Project Overview +## OVERVIEW +Monorepo for YouVersion Platform SDKs (React Web). pnpm workspaces + Turbo, 3 published packages with unified versioning. -This is a monorepo for YouVersion Platform SDKs for React Web. The project uses pnpm workspaces, TypeScript, and Turbo for build orchestration. - -## Development Commands +## STRUCTURE +``` +packages/ + core/ @youversion/platform-core (API clients, utilities) + hooks/ @youversion/platform-react-hooks (React hooks) + ui/ @youversion/platform-react-ui (UI components) +tools/ Shared configs (TS, ESLint) +``` -### Essential Commands -```bash -# Install dependencies (requires pnpm >= 9.0.0) -pnpm install +## KEY PATTERNS -# Build all packages in correct order -pnpm build +**Unified versioning**: All 3 packages share exact same version, always released together -# Run tests across all packages (sequential execution for clear output) -pnpm test +**Build order enforced by Turbo**: core → hooks → ui (dependency chain) -# Type checking -pnpm typecheck +**React 19.1.2 exact pinning**: pnpm overrides lock all React packages to exact version -# Linting -pnpm lint +**Tailwind CSS injection**: Auto-injected as JS constant via tsup define (no build step) -# Format code -pnpm format +**Changeset workflow**: pnpm changeset → pnpm version-packages → pnpm release -# Start development environment -pnpm dev:web # For React SDK development -``` +**Trusted publishing**: OIDC-based npm publishing (no tokens) -### Package-Specific Commands -```bash -# Build specific packages -pnpm build:core # Build core -pnpm build:react # Build React SDK +**Pre-commit**: Husky + lint-staged runs ESLint + Prettier on staged files -# Run tests in watch mode -pnpm test:watch +## ANTI-PATTERNS -# Run individual package tests with coverage -pnpm --filter @youversion/platform-core test:coverage -pnpm --filter @youversion/platform-react-hooks test:coverage +❌ Don't assume shared source directory (each package self-contained) +❌ Don't use API Extractor (listed but not actually used) +❌ Don't expect consistent build tools (core: tsup, hooks: tsc only, ui: tsup + tsc) +❌ Don't modify React version (exact 19.1.2 enforced via pnpm overrides) +❌ Don't use npm/yarn (only pnpm >= 9.0.0 supported) +❌ Don't break unified versioning (all packages versioned together) -# Build and verify outputs -pnpm build -``` +## COMMANDS -### Release Process ```bash -# Create a changeset for version updates -pnpm changeset - -# Version packages based on changesets -pnpm version-packages - -# Build and publish packages -pnpm release +# Setup +pnpm install # Requires pnpm >= 9.0.0, Node >= 20.0.0 + +# Build +pnpm build # Turbo builds all in dependency order +pnpm build:core # Build core only +pnpm build:hooks # Build hooks only +pnpm build:react # Build UI only + +# Development +pnpm dev:web # Start UI dev server with hot reload +pnpm test # Run tests sequentially across all packages +pnpm test:watch # Watch mode for all packages +pnpm test:coverage # Coverage reports for all packages + +# Quality +pnpm lint # ESLint all packages +pnpm typecheck # Type check all packages +pnpm format # Format all code + +# Release +pnpm changeset # Create changeset entry +pnpm version-packages # Apply changesets to versions +pnpm release # Build + publish all packages ``` -## Architecture - -### Monorepo Structure -``` -├── packages/ -│ ├── core/ # @youversion/platform-core - Published core package -│ ├── hooks/ # @youversion/platform-react-hooks - Published React hooks -│ └── ui/ # @youversion/platform-react-ui - Published React SDK -├── tools/ # Shared configs (TypeScript, ESLint, Jest) -└── scripts/ # Build and development scripts -``` +## CRITICAL GOTCHAS -### Key Architectural Patterns - -1. **Package Dependencies**: - - `core` is the foundation (API clients, utilities) - - `hooks` depends on `core` - - `ui` depends on both `hooks` and `core` - -2. **Build Order**: Dependencies must be built in order: - - First: `core` - - Second: `hooks` - - Finally: `ui` - -3. **Unified Versioning**: All published packages share the same version number and are released together - -4. **UI Components**: All UI components use React.forwardRef and accept standard HTML attributes - -5. **TypeScript Configuration**: Shared configs in `tools/tsconfig/` - -6. **Testing**: - - All packages use Vitest - - Test files follow `*.test.ts(x)` pattern - -### Build System - -- **Turbo**: Orchestrates builds with caching and dependency management -- **tsup**: Bundles TypeScript for packages -- **API Extractor**: Generates single .d.ts file for published packages -- **Changesets**: Manages versioning and changelogs - -### Code Quality - -- **Pre-commit hooks**: Husky runs lint-staged on git commits -- **Lint-staged**: Runs ESLint and Prettier on staged files -- **TypeScript**: Strict mode enabled, no implicit any -- **ESLint**: Shared config from `tools/eslint-config/` - -### Publishing - -- Published packages: - - `@youversion/platform-core` - - `@youversion/platform-react-hooks` - - `@youversion/platform-react-ui` -- All packages use unified versioning (same version number) -- NPM registry: https://registry.npmjs.org/ -- Access: public - -## Review Guidelines - -When conducting code reviews, AI agents should systematically evaluate the following aspects: - -### Code Standards and Conventions -- Do the changes follow the established conventions and patterns used throughout the codebase? -- Is the code style consistent with existing code (indentation, naming conventions, file organization)? -- Are the appropriate design patterns being used where applicable? -- Does the code follow the monorepo structure and package boundaries? -- Are TypeScript types properly defined and avoiding `any` types? -- Do components follow the React.forwardRef pattern for UI components? - -### Security Assessment -- Do the changes introduce any security vulnerabilities or risks? -- Are user inputs properly validated and sanitized? -- Is sensitive data properly handled and protected? -- Are authentication and authorization checks properly implemented? -- Are there any exposed API keys, credentials, or sensitive configuration data? -- Are network requests using appropriate security protocols (HTTPS, proper headers)? -- Is XSS protection properly implemented (no dangerouslySetInnerHTML without sanitization)? -- Are Content Security Policy considerations met? - -### Performance Considerations -- Do the changes introduce potential performance bottlenecks? -- Are there any inefficient algorithms or data structures being used? -- Is there unnecessary re-rendering or state updates in React components? -- Are React hooks (useMemo, useCallback, memo) used appropriately to prevent unnecessary renders? -- Are large lists properly virtualized where appropriate? -- Is lazy loading implemented for heavy resources and code splitting used effectively? -- Are bundle sizes kept reasonable (check with build output)? -- Is tree-shaking working properly for unused exports? -- Are web vitals (LCP, FID, CLS) maintained or improved? - -### React/TypeScript Best Practices -- Are components properly optimized using React.memo, useMemo, and useCallback where appropriate? -- Is component composition preferred over prop drilling? -- Are custom hooks following the Rules of Hooks? -- Is proper error boundary implementation in place? -- Are TypeScript generics used effectively for reusable components? -- Is strict mode TypeScript being followed (no implicit any, proper null checking)? -- Are discriminated unions used for complex state management? -- Are React 18+ features (Suspense, concurrent features) used appropriately? - -### Package Architecture -- Does the code respect package boundaries (core → hooks → ui dependency order)? -- Are internal APIs properly exported through package index files? -- Is the unified versioning strategy maintained? -- Are workspace dependencies correctly referenced? -- Does the code follow the established build order requirements? - -### Functional Verification -- Does the code actually implement what the PR description claims? -- Are all acceptance criteria from the related issue/ticket met? -- Are edge cases properly handled? -- Is error handling comprehensive and user-friendly? -- Are all promised features fully implemented and working? -- Do changes work across all supported browsers? - -### Testing and Documentation -- Are appropriate tests included for new functionality (using Vitest)? -- Do tests follow the *.test.ts(x) naming pattern? -- Do existing tests still pass? -- Is the code self-documenting with clear variable and function names? -- Are complex logic sections properly commented? -- Are API changes documented with proper TypeScript JSDoc? -- Are breaking changes clearly identified in changesets? -- Is test coverage maintained or improved? - -### Dependencies and Compatibility -- Are new dependencies necessary and well-maintained? -- Do new dependencies have appropriate TypeScript types? -- Are version requirements appropriate and following semver? -- Is backward compatibility maintained where expected? -- Are deprecated APIs avoided? -- Are peer dependencies properly defined for the published packages? -- Is the minimum Node.js version (>= 20.0.0) respected? - -### Build System and Tooling -- Do changes work with the Turbo build cache? -- Are tsup configurations properly maintained? -- Does API Extractor successfully generate type definitions? -- Do lint and format commands pass successfully? -- Are pre-commit hooks passing? -- Are changeset entries created for user-facing changes? - -### Accessibility -- Are ARIA attributes properly implemented? -- Is keyboard navigation fully supported? -- Are focus states clearly visible? -- Do interactive elements have appropriate roles? -- Are form inputs properly labeled? -- Is color contrast WCAG compliant? -- Are screen reader announcements appropriate? - -### User Experience -- Do the changes provide a smooth and intuitive user experience? -- Are loading states and error states properly handled? -- Is feedback provided for user actions? -- Are animations performant and purposeful (respecting prefers-reduced-motion)? -- Is responsive design maintained across viewport sizes? -- Are browser-specific quirks handled appropriately? - -### Developer Experience -- Is the API intuitive and consistent with existing patterns? -- Are TypeScript types providing good IDE support and autocomplete? -- Are error messages helpful and actionable? -- Is the component API well-designed and flexible? -- Are props properly documented with JSDoc comments? -- Are examples provided for complex usage patterns? - -## Important Notes - -1. Always run `pnpm install` after pulling changes -2. Use `pnpm` (not npm or yarn) for all operations -3. Node.js >= 20.0.0 required -4. When modifying packages, rebuild dependent packages in order (core → hooks → ui) -5. All packages use unified versioning - they're always released together at the same version +- Always rebuild dependent packages after modifying core or hooks +- Turbo build cache can skip changes - run `turbo build --force` if needed +- Changesets required for ALL version bumps (even patches) +- Pre-commit hooks fail if typecheck or lint fails +- Workspace protocol: use `workspace:*` in package.json dependencies diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md new file mode 100644 index 0000000..f55854d --- /dev/null +++ b/packages/core/AGENTS.md @@ -0,0 +1,36 @@ +## OVERVIEW +Foundation package providing pure TypeScript API clients for YouVersion services with zero React dependencies. + +## STRUCTURE +``` +schemas/ # Zod schemas for all data types (schema-first design) +client.ts # ApiClient - main HTTP client +bible.ts # BibleClient - Bible data operations +languages.ts # LanguagesClient - language data +highlights.ts # HighlightsClient - user highlights +YouVersionAPI.ts # Base YouVersion API client +SignInWithYouVersionPKCE.ts # PKCE auth implementation +StorageStrategy.ts # Storage interface (SessionStorage, MemoryStorage) +``` + +## PUBLIC API +- `ApiClient`: Main HTTP client with auth handling +- `BibleClient`: Fetch Bibles, chapters, verses, versions +- `LanguagesClient`: Get available languages +- `HighlightsClient`: Manage user highlights +- `SignInWithYouVersionPKCE()`: PKCE auth flow function +- `SessionStorage`, `MemoryStorage`: Storage strategies + +## CONVENTIONS +- Schema-first: All types defined in schemas/*.ts using Zod +- Zero React: Pure TypeScript, no React dependencies +- Storage: Abstract via StorageStrategy interface +- Auth: PKCE flow with pluggable storage backends +- Error handling: Zod validation for all API responses + +## TESTING +- Framework: Vitest with Node environment +- Mocking: MSW for API endpoints +- Integration: Set `INTEGRATION_TESTS=true` for real API tests +- Coverage: @vitest/coverage-v8 +- Files: 12 test files covering all clients and auth diff --git a/packages/core/CLAUDE.md b/packages/core/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/core/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/hooks/AGENTS.md b/packages/hooks/AGENTS.md new file mode 100644 index 0000000..f22dd97 --- /dev/null +++ b/packages/hooks/AGENTS.md @@ -0,0 +1,27 @@ +# @youversion/platform-react-hooks + +## OVERVIEW +React integration layer providing 20+ data fetching hooks and 3 core providers. + +## STRUCTURE +- `use*.ts` - Data fetching hooks (useBook, useChapter, usePassage, useVersion, etc.) +- `context/` - Providers and contexts (separate files, exported via index.ts) +- `utility/` - Helper functions (useDebounce, extractTextFromHTML, extractVersesFromHTML) + +## PUBLIC API +- 20+ data fetching hooks for YouVersion API resources +- YouVersionProvider - Core SDK configuration +- YouVersionAuthProvider - Authentication state +- ReaderProvider - Reading session context +- Utility functions exported from utility/index + +## CONVENTIONS +- Context and Provider in separate files +- All contexts exported via context/index.ts +- TypeScript declarations generated separately (no bundling) +- Build: tsc only + +## TESTING +- Vitest with jsdom environment +- React Testing Library for component tests +- 9 test files covering hooks and providers diff --git a/packages/hooks/CLAUDE.md b/packages/hooks/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/hooks/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md new file mode 100644 index 0000000..ea1a80c --- /dev/null +++ b/packages/ui/AGENTS.md @@ -0,0 +1,46 @@ +# AGENTS.md + +## OVERVIEW +Complete UI layer with 7 Bible components: BibleTextView, VerseOfTheDay, BibleReader, BibleChapterPicker, BibleVersionPicker, YouVersionAuthButton, BibleWidgetView, BibleAppLogoLockup + +## STRUCTURE +``` +components/ # Public Bible components (exported) +components/ui/ # Internal Radix primitives (not exported) +lib/ # Utilities (injectStyles, utils) +src/index.ts # Entry point with style injection side effect +``` + +## PUBLIC API +- Components exported from `src/components/` +- Re-exports: `YouVersionProvider`, `useYVAuth` from @youversion/platform-react-hooks +- All components use React.forwardRef, accept standard HTML attributes + +## CONVENTIONS +- React 19.1.2+ peer dependency +- Radix UI primitives for accessibility +- Tailwind CSS via @tailwindcss/cli 4.1.15 +- tsup for bundling, tsc for type declarations + +## STYLING +**Auto-injected on import**: `src/index.ts` calls `injectStyles()` on module load +- CSS embedded as `__YV_STYLES__` constant via tsup define (no separate CSS file) +- Built Tailwind CSS: `dist/tailwind.css` → injected as JS string at build time +- Light/dark mode via CSS variables (`[data-yv-sdk]`) + +## TESTING +- Vitest + jsdom for unit tests (`*.test.tsx`) +- Playwright for Storybook integration tests (`vitest run --project storybook`) +- Test setup: `src/test/setup.ts` + +## BUILD ORDER +```bash +pnpm build:css # Tailwind build + strip-layers.js +pnpm build:js # tsup bundling with __YV_STYLES__ injection +pnpm build:types # tsc declarations +``` + +## CRITICAL +- **Side effect**: importing package injects styles automatically +- Never skip build:css step (styles required for __YV_STYLES__ constant) +- Always rebuild after CSS changes diff --git a/packages/ui/CLAUDE.md b/packages/ui/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/ui/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From a511269b356f8e090217dfed25d835639a43ae8d Mon Sep 17 00:00:00 2001 From: cameronapak Date: Tue, 6 Jan 2026 12:36:55 -0600 Subject: [PATCH 02/14] feat: add Michael Martin's review guidelines for AI agents with greptile instructions --- docs/review-guidelines.md | 109 ++++++++++++++++++++++++++++++++++++++ greptile.json | 43 +++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 docs/review-guidelines.md create mode 100644 greptile.json diff --git a/docs/review-guidelines.md b/docs/review-guidelines.md new file mode 100644 index 0000000..bf34ea6 --- /dev/null +++ b/docs/review-guidelines.md @@ -0,0 +1,109 @@ +## Review Guidelines + +When conducting code reviews, AI agents should systematically evaluate the following aspects: + +### Code Standards and Conventions +- Do the changes follow the established conventions and patterns used throughout the codebase? +- Is the code style consistent with existing code (indentation, naming conventions, file organization)? +- Are the appropriate design patterns being used where applicable? +- Does the code follow the monorepo structure and package boundaries? +- Are TypeScript types properly defined and avoiding `any` types? +- Do components follow the React.forwardRef pattern for UI components? + +### Security Assessment +- Do the changes introduce any security vulnerabilities or risks? +- Are user inputs properly validated and sanitized? +- Is sensitive data properly handled and protected? +- Are authentication and authorization checks properly implemented? +- Are there any exposed API keys, credentials, or sensitive configuration data? +- Are network requests using appropriate security protocols (HTTPS, proper headers)? +- Is XSS protection properly implemented (no dangerouslySetInnerHTML without sanitization)? +- Are Content Security Policy considerations met? + +### Performance Considerations +- Do the changes introduce potential performance bottlenecks? +- Are there any inefficient algorithms or data structures being used? +- Is there unnecessary re-rendering or state updates in React components? +- Are React hooks (useMemo, useCallback, memo) used appropriately to prevent unnecessary renders? +- Are large lists properly virtualized where appropriate? +- Is lazy loading implemented for heavy resources and code splitting used effectively? +- Are bundle sizes kept reasonable (check with build output)? +- Is tree-shaking working properly for unused exports? +- Are web vitals (LCP, FID, CLS) maintained or improved? + +### React/TypeScript Best Practices +- Are components properly optimized using React.memo, useMemo, and useCallback where appropriate? +- Is component composition preferred over prop drilling? +- Are custom hooks following the Rules of Hooks? +- Is proper error boundary implementation in place? +- Are TypeScript generics used effectively for reusable components? +- Is strict mode TypeScript being followed (no implicit any, proper null checking)? +- Are discriminated unions used for complex state management? +- Are React 18+ features (Suspense, concurrent features) used appropriately? + +### Package Architecture +- Does the code respect package boundaries (core → hooks → ui dependency order)? +- Are internal APIs properly exported through package index files? +- Is the unified versioning strategy maintained? +- Are workspace dependencies correctly referenced? +- Does the code follow the established build order requirements? + +### Functional Verification +- Does the code actually implement what the PR description claims? +- Are all acceptance criteria from the related issue/ticket met? +- Are edge cases properly handled? +- Is error handling comprehensive and user-friendly? +- Are all promised features fully implemented and working? +- Do changes work across all supported browsers? + +### Testing and Documentation +- Are appropriate tests included for new functionality (using Vitest)? +- Do tests follow the *.test.ts(x) naming pattern? +- Do existing tests still pass? +- Is the code self-documenting with clear variable and function names? +- Are complex logic sections properly commented? +- Are API changes documented with proper TypeScript JSDoc? +- Are breaking changes clearly identified in changesets? +- Is test coverage maintained or improved? + +### Dependencies and Compatibility +- Are new dependencies necessary and well-maintained? +- Do new dependencies have appropriate TypeScript types? +- Are version requirements appropriate and following semver? +- Is backward compatibility maintained where expected? +- Are deprecated APIs avoided? +- Are peer dependencies properly defined for the published packages? +- Is the minimum Node.js version (>= 20.0.0) respected? + +### Build System and Tooling +- Do changes work with the Turbo build cache? +- Are tsup configurations properly maintained? +- Does API Extractor successfully generate type definitions? +- Do lint and format commands pass successfully? +- Are pre-commit hooks passing? +- Are changeset entries created for user-facing changes? + +### Accessibility +- Are ARIA attributes properly implemented? +- Is keyboard navigation fully supported? +- Are focus states clearly visible? +- Do interactive elements have appropriate roles? +- Are form inputs properly labeled? +- Is color contrast WCAG compliant? +- Are screen reader announcements appropriate? + +### User Experience +- Do the changes provide a smooth and intuitive user experience? +- Are loading states and error states properly handled? +- Is feedback provided for user actions? +- Are animations performant and purposeful (respecting prefers-reduced-motion)? +- Is responsive design maintained across viewport sizes? +- Are browser-specific quirks handled appropriately? + +### Developer Experience +- Is the API intuitive and consistent with existing patterns? +- Are TypeScript types providing good IDE support and autocomplete? +- Are error messages helpful and actionable? +- Is the component API well-designed and flexible? +- Are props properly documented with JSDoc comments? +- Are examples provided for complex usage patterns? diff --git a/greptile.json b/greptile.json new file mode 100644 index 0000000..770fb95 --- /dev/null +++ b/greptile.json @@ -0,0 +1,43 @@ +{ + "commentTypes": ["logic", "syntax", "style"], + "instructions": "Enforce project-specific review guidelines - see docs/review-guidelines.md for complete checklist", + "customContext": { + "rules": [ + { + "scope": ["src/**/*.ts", "src/**/*.tsx", "packages/**/*.ts", "packages/**/*.tsx"], + "rule": "All components must use React.forwardRef and accept standard HTML attributes" + }, + { + "scope": ["src/**"], + "rule": "Package dependencies must follow core → hooks → ui dependency order" + }, + { + "scope": ["src/**"], + "rule": "Always use workspace:* protocol for internal dependencies" + }, + { + "scope": ["src/**"], + "rule": "Schema-first: All types defined in schemas/*.ts using Zod" + }, + { + "scope": ["packages/core/src/**"], + "rule": "Zero React: Pure TypeScript, no React dependencies" + }, + { + "scope": ["packages/hooks/src/context/**"], + "rule": "Context and Provider in separate files, exported via context/index.ts" + }, + { + "scope": ["packages/ui/src/**"], + "rule": "Auto-injected styles: index.ts calls injectStyles() on module load" + } + ], + "files": [ + { + "scope": ["*"], + "path": "docs/review-guidelines.md", + "description": "Comprehensive review checklist for all pull requests" + } + ] + } +} From 0649e8b2f0d0a360dcfa8ab8bb1ed9da3e8916b5 Mon Sep 17 00:00:00 2001 From: cameronapak Date: Tue, 6 Jan 2026 12:43:57 -0600 Subject: [PATCH 03/14] docs(agents): update wording to "many" to avoid per-PR updates Updated the wording to say "many" versus having very specific numbers that would have to be updated on every PR. This simplifies it so that AI gets the information it needs and we don't have to update this. --- packages/core/AGENTS.md | 2 +- packages/hooks/AGENTS.md | 2 +- packages/ui/AGENTS.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md index f55854d..bb2bbd5 100644 --- a/packages/core/AGENTS.md +++ b/packages/core/AGENTS.md @@ -33,4 +33,4 @@ StorageStrategy.ts # Storage interface (SessionStorage, MemoryStorage) - Mocking: MSW for API endpoints - Integration: Set `INTEGRATION_TESTS=true` for real API tests - Coverage: @vitest/coverage-v8 -- Files: 12 test files covering all clients and auth +- Files: Many test files covering all clients and auth diff --git a/packages/hooks/AGENTS.md b/packages/hooks/AGENTS.md index f22dd97..b27388f 100644 --- a/packages/hooks/AGENTS.md +++ b/packages/hooks/AGENTS.md @@ -24,4 +24,4 @@ React integration layer providing 20+ data fetching hooks and 3 core providers. ## TESTING - Vitest with jsdom environment - React Testing Library for component tests -- 9 test files covering hooks and providers +- Many test files covering hooks and providers diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md index ea1a80c..dd18ead 100644 --- a/packages/ui/AGENTS.md +++ b/packages/ui/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md ## OVERVIEW -Complete UI layer with 7 Bible components: BibleTextView, VerseOfTheDay, BibleReader, BibleChapterPicker, BibleVersionPicker, YouVersionAuthButton, BibleWidgetView, BibleAppLogoLockup +Complete UI layer with many Bible components: BibleTextView, VerseOfTheDay, BibleReader, BibleChapterPicker, BibleVersionPicker, YouVersionAuthButton, BibleWidgetView, BibleAppLogoLockup ## STRUCTURE ``` From dc5333c78a067564df81931a96f54814450d1a7c Mon Sep 17 00:00:00 2001 From: cameronapak Date: Tue, 6 Jan 2026 12:57:24 -0600 Subject: [PATCH 04/14] docs: add updates based on feedback from Greptile's AI agent review --- AGENTS.md | 2 ++ greptile.json | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index abbbb68..5d27813 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,3 +73,5 @@ pnpm release # Build + publish all packages - Changesets required for ALL version bumps (even patches) - Pre-commit hooks fail if typecheck or lint fails - Workspace protocol: use `workspace:*` in package.json dependencies +- **Unified versioning**: All packages must share exact same version - never version packages independently +- **Node.js requirement**: Minimum version 20.0.0 required for all environments diff --git a/greptile.json b/greptile.json index 770fb95..8892279 100644 --- a/greptile.json +++ b/greptile.json @@ -19,6 +19,10 @@ "scope": ["src/**"], "rule": "Schema-first: All types defined in schemas/*.ts using Zod" }, + { + "scope": ["packages/**"], + "rule": "Unified versioning: All packages must maintain exact same version - never version packages independently" + }, { "scope": ["packages/core/src/**"], "rule": "Zero React: Pure TypeScript, no React dependencies" From 00de3bdddaafd19758e58c0440909fbb46dd656c Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 15:40:49 -0600 Subject: [PATCH 05/14] docs(AGENTS): update AGENTS.md documentation Improve descriptions in AGENTS.md files for core, hooks, and ui packages. This clarifies the purpose of each package and its key features. --- packages/core/AGENTS.md | 14 +++++++------- packages/hooks/AGENTS.md | 4 ++-- packages/ui/AGENTS.md | 4 ++-- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md index bb2bbd5..92f8d2b 100644 --- a/packages/core/AGENTS.md +++ b/packages/core/AGENTS.md @@ -3,14 +3,14 @@ Foundation package providing pure TypeScript API clients for YouVersion services ## STRUCTURE ``` -schemas/ # Zod schemas for all data types (schema-first design) -client.ts # ApiClient - main HTTP client -bible.ts # BibleClient - Bible data operations -languages.ts # LanguagesClient - language data -highlights.ts # HighlightsClient - user highlights -YouVersionAPI.ts # Base YouVersion API client +schemas/ # Zod schemas for all data types (schema-first design) +client.ts # ApiClient - main HTTP client +bible.ts # BibleClient - Bible data operations +languages.ts # LanguagesClient - language data +highlights.ts # HighlightsClient - user highlights +YouVersionAPI.ts # Base YouVersion API client SignInWithYouVersionPKCE.ts # PKCE auth implementation -StorageStrategy.ts # Storage interface (SessionStorage, MemoryStorage) +StorageStrategy.ts # Storage interface (SessionStorage, MemoryStorage) ``` ## PUBLIC API diff --git a/packages/hooks/AGENTS.md b/packages/hooks/AGENTS.md index b27388f..24be07f 100644 --- a/packages/hooks/AGENTS.md +++ b/packages/hooks/AGENTS.md @@ -1,7 +1,7 @@ # @youversion/platform-react-hooks ## OVERVIEW -React integration layer providing 20+ data fetching hooks and 3 core providers. +React integration layer providing many data fetching hooks with 3 core providers: YouVersionProvider, YouVersionAuthProvider, and ReaderProvider. ## STRUCTURE - `use*.ts` - Data fetching hooks (useBook, useChapter, usePassage, useVersion, etc.) @@ -9,7 +9,7 @@ React integration layer providing 20+ data fetching hooks and 3 core providers. - `utility/` - Helper functions (useDebounce, extractTextFromHTML, extractVersesFromHTML) ## PUBLIC API -- 20+ data fetching hooks for YouVersion API resources +- Data fetching hooks for YouVersion API resources - YouVersionProvider - Core SDK configuration - YouVersionAuthProvider - Authentication state - ReaderProvider - Reading session context diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md index dd18ead..3dd240f 100644 --- a/packages/ui/AGENTS.md +++ b/packages/ui/AGENTS.md @@ -17,9 +17,9 @@ src/index.ts # Entry point with style injection side effect - All components use React.forwardRef, accept standard HTML attributes ## CONVENTIONS -- React 19.1.2+ peer dependency +- React 19+ peer dependency - Radix UI primitives for accessibility -- Tailwind CSS via @tailwindcss/cli 4.1.15 +- Tailwind CSS via @tailwindcss/cli v4 - tsup for bundling, tsc for type declarations ## STYLING From 4fc74c18d3996074f814e44576a4a52f9c253c7b Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 15:45:20 -0600 Subject: [PATCH 06/14] docs(hooks): update AGENTS.md with public API examples Add specific examples of data fetching hooks to the AGENTS.md file for the hooks package. --- packages/hooks/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/hooks/AGENTS.md b/packages/hooks/AGENTS.md index 24be07f..bac20c4 100644 --- a/packages/hooks/AGENTS.md +++ b/packages/hooks/AGENTS.md @@ -9,7 +9,7 @@ React integration layer providing many data fetching hooks with 3 core providers - `utility/` - Helper functions (useDebounce, extractTextFromHTML, extractVersesFromHTML) ## PUBLIC API -- Data fetching hooks for YouVersion API resources +- Data fetching hooks: useBook, useChapter, usePassage, useVersion, etc. - YouVersionProvider - Core SDK configuration - YouVersionAuthProvider - Authentication state - ReaderProvider - Reading session context From 50d34bdc8fa49ab145ba23ec69a6637df0af11cc Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 16:03:28 -0600 Subject: [PATCH 07/14] docs(components): add clarity on component styles --- packages/ui/AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md index 3dd240f..bf1def5 100644 --- a/packages/ui/AGENTS.md +++ b/packages/ui/AGENTS.md @@ -27,6 +27,7 @@ src/index.ts # Entry point with style injection side effect - CSS embedded as `__YV_STYLES__` constant via tsup define (no separate CSS file) - Built Tailwind CSS: `dist/tailwind.css` → injected as JS string at build time - Light/dark mode via CSS variables (`[data-yv-sdk]`) +- For the theme to be applied to our components, we add a `data-yv-sdk` attribute on the parent containing element ## TESTING - Vitest + jsdom for unit tests (`*.test.tsx`) From 723a41770853ba85aaab8dc1de063209153051eb Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 16:04:42 -0600 Subject: [PATCH 08/14] refactor(components): remove forwardRef requirement --- docs/review-guidelines.md | 1 - greptile.json | 4 ---- packages/ui/AGENTS.md | 1 - 3 files changed, 6 deletions(-) diff --git a/docs/review-guidelines.md b/docs/review-guidelines.md index bf34ea6..dc84df7 100644 --- a/docs/review-guidelines.md +++ b/docs/review-guidelines.md @@ -8,7 +8,6 @@ When conducting code reviews, AI agents should systematically evaluate the follo - Are the appropriate design patterns being used where applicable? - Does the code follow the monorepo structure and package boundaries? - Are TypeScript types properly defined and avoiding `any` types? -- Do components follow the React.forwardRef pattern for UI components? ### Security Assessment - Do the changes introduce any security vulnerabilities or risks? diff --git a/greptile.json b/greptile.json index 8892279..2c1059e 100644 --- a/greptile.json +++ b/greptile.json @@ -3,10 +3,6 @@ "instructions": "Enforce project-specific review guidelines - see docs/review-guidelines.md for complete checklist", "customContext": { "rules": [ - { - "scope": ["src/**/*.ts", "src/**/*.tsx", "packages/**/*.ts", "packages/**/*.tsx"], - "rule": "All components must use React.forwardRef and accept standard HTML attributes" - }, { "scope": ["src/**"], "rule": "Package dependencies must follow core → hooks → ui dependency order" diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md index bf1def5..a77e147 100644 --- a/packages/ui/AGENTS.md +++ b/packages/ui/AGENTS.md @@ -14,7 +14,6 @@ src/index.ts # Entry point with style injection side effect ## PUBLIC API - Components exported from `src/components/` - Re-exports: `YouVersionProvider`, `useYVAuth` from @youversion/platform-react-hooks -- All components use React.forwardRef, accept standard HTML attributes ## CONVENTIONS - React 19+ peer dependency From 6f668be60574c13b532c503bd48409d03cdbca64 Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 16:11:36 -0600 Subject: [PATCH 09/14] docs: add clarity around mock APIs for hooks AGENTS.md --- packages/hooks/AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/hooks/AGENTS.md b/packages/hooks/AGENTS.md index bac20c4..45bb1a4 100644 --- a/packages/hooks/AGENTS.md +++ b/packages/hooks/AGENTS.md @@ -25,3 +25,4 @@ React integration layer providing many data fetching hooks with 3 core providers - Vitest with jsdom environment - React Testing Library for component tests - Many test files covering hooks and providers +- Mock API's live in `__tests__/mocks` From ebf3dab4b6460f9d2d3681b04123bdbe9b963285 Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 16:13:22 -0600 Subject: [PATCH 10/14] docs(tailwind): add note about css prefixing --- packages/ui/AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md index a77e147..5dbf567 100644 --- a/packages/ui/AGENTS.md +++ b/packages/ui/AGENTS.md @@ -27,6 +27,7 @@ src/index.ts # Entry point with style injection side effect - Built Tailwind CSS: `dist/tailwind.css` → injected as JS string at build time - Light/dark mode via CSS variables (`[data-yv-sdk]`) - For the theme to be applied to our components, we add a `data-yv-sdk` attribute on the parent containing element +- Tailwind CSS classes must be prefixed with `yv:` to prevent class naming collision when someone uses our components in their app. For example, `mt-4` becomes `yv:mt-4` ## TESTING - Vitest + jsdom for unit tests (`*.test.tsx`) From 398ae791c511cdc2386177d535f198323142b589 Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 16:15:09 -0600 Subject: [PATCH 11/14] chore(storybook): update integration test command Replace `vitest run --project storybook` with `pnpm test:integration` for consistency across the project. Also add a note about tagging integration tests for better organization. --- packages/ui/AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md index 5dbf567..cb01dc4 100644 --- a/packages/ui/AGENTS.md +++ b/packages/ui/AGENTS.md @@ -31,7 +31,8 @@ src/index.ts # Entry point with style injection side effect ## TESTING - Vitest + jsdom for unit tests (`*.test.tsx`) -- Playwright for Storybook integration tests (`vitest run --project storybook`) +- Playwright for Storybook integration tests (`pnpm test:integration`) +- All Storybook tests with a play function need to have a `tags: ['integration']` - Test setup: `src/test/setup.ts` ## BUILD ORDER From 67562731988dea5ef851ee7449b69d08b70e8b15 Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 16:27:45 -0600 Subject: [PATCH 12/14] docs(agents): add theme token usage documentation --- packages/ui/AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md index cb01dc4..3a73567 100644 --- a/packages/ui/AGENTS.md +++ b/packages/ui/AGENTS.md @@ -25,9 +25,10 @@ src/index.ts # Entry point with style injection side effect **Auto-injected on import**: `src/index.ts` calls `injectStyles()` on module load - CSS embedded as `__YV_STYLES__` constant via tsup define (no separate CSS file) - Built Tailwind CSS: `dist/tailwind.css` → injected as JS string at build time -- Light/dark mode via CSS variables (`[data-yv-sdk]`) - For the theme to be applied to our components, we add a `data-yv-sdk` attribute on the parent containing element - Tailwind CSS classes must be prefixed with `yv:` to prevent class naming collision when someone uses our components in their app. For example, `mt-4` becomes `yv:mt-4` +- Light/dark mode via CSS variables (`[data-yv-sdk]`) +- Use semantic theme tokens (`yv:text-muted-foreground`, `yv:bg-destructive`) instead of arbitrary color values ## TESTING - Vitest + jsdom for unit tests (`*.test.tsx`) From 2ca4ddde187705f2a40245f68d6afd4a5fc0f6f2 Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 16:30:08 -0600 Subject: [PATCH 13/14] docs: add notes on inter-package testing --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5d27813..7c4c05f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,3 +75,5 @@ pnpm release # Build + publish all packages - Workspace protocol: use `workspace:*` in package.json dependencies - **Unified versioning**: All packages must share exact same version - never version packages independently - **Node.js requirement**: Minimum version 20.0.0 required for all environments +- One change in a package could break something in another package, so we want to make sure that all tests are passing across the packages before code gets pushed +- When stuck, ask clarifying questions From abf9908fcf84594b96129537c4f0b80bae57532d Mon Sep 17 00:00:00 2001 From: cameronapak Date: Mon, 12 Jan 2026 16:41:23 -0600 Subject: [PATCH 14/14] docs: Refactor AGENTS.md with structure and clarity --- AGENTS.md | 135 +++++++++++++++++++++++++++++---------- packages/core/AGENTS.md | 43 ++++++++++++- packages/hooks/AGENTS.md | 48 ++++++++++++-- packages/ui/AGENTS.md | 37 ++++++++++- 4 files changed, 221 insertions(+), 42 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7c4c05f..5c0c2fc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,40 @@ -# AGENTS.md +# YouVersion Platform SDKs – Agent Guide + +## QUICK FACTS +- Monorepo: pnpm workspaces + Turborepo +- Packages: + - `@youversion/platform-core` (pure TS API clients) + - `@youversion/platform-react-hooks` (React hooks layer) + - `@youversion/platform-react-ui` (UI components) +- Language: TypeScript +- Test runner: Vitest +- Node: >= 20.0.0 +- Package manager: pnpm >= 9.0.0 (no npm/yarn) + +## WHERE TO MAKE CHANGES + +- **New or changed API endpoints / data types** + → Add/update Zod schemas and clients in `packages/core` +- **New React data hooks / provider behavior** + → Implement in `packages/hooks` using `@youversion/platform-core` clients +- **New visual components / styling / UX** + → Implement in `packages/ui` using hooks from `@youversion/platform-react-hooks` + +**Rule of thumb:** +- Core = network + types (no React) +- Hooks = React logic/state around core +- UI = components and styling around hooks + +## DEPENDENCY GRAPH -## OVERVIEW -Monorepo for YouVersion Platform SDKs (React Web). pnpm workspaces + Turbo, 3 published packages with unified versioning. +``` +@youversion/platform-core → @youversion/platform-react-hooks → @youversion/platform-react-ui + (pure TS) (React hooks) (React components) +``` + +- Do not introduce reverse dependencies +- Do not import UI or hooks from core +- Do not import UI from hooks ## STRUCTURE ``` @@ -12,31 +45,6 @@ packages/ tools/ Shared configs (TS, ESLint) ``` -## KEY PATTERNS - -**Unified versioning**: All 3 packages share exact same version, always released together - -**Build order enforced by Turbo**: core → hooks → ui (dependency chain) - -**React 19.1.2 exact pinning**: pnpm overrides lock all React packages to exact version - -**Tailwind CSS injection**: Auto-injected as JS constant via tsup define (no build step) - -**Changeset workflow**: pnpm changeset → pnpm version-packages → pnpm release - -**Trusted publishing**: OIDC-based npm publishing (no tokens) - -**Pre-commit**: Husky + lint-staged runs ESLint + Prettier on staged files - -## ANTI-PATTERNS - -❌ Don't assume shared source directory (each package self-contained) -❌ Don't use API Extractor (listed but not actually used) -❌ Don't expect consistent build tools (core: tsup, hooks: tsc only, ui: tsup + tsc) -❌ Don't modify React version (exact 19.1.2 enforced via pnpm overrides) -❌ Don't use npm/yarn (only pnpm >= 9.0.0 supported) -❌ Don't break unified versioning (all packages versioned together) - ## COMMANDS ```bash @@ -66,14 +74,77 @@ pnpm version-packages # Apply changesets to versions pnpm release # Build + publish all packages ``` +## PER-PACKAGE COMMANDS + +```bash +# Core +pnpm --filter @youversion/platform-core test +pnpm --filter @youversion/platform-core build + +# Hooks +pnpm --filter @youversion/platform-react-hooks test +pnpm --filter @youversion/platform-react-hooks build + +# UI +pnpm --filter @youversion/platform-react-ui test +pnpm --filter @youversion/platform-react-ui build +``` + +## KEY PATTERNS + +**Unified versioning**: All 3 packages share exact same version, always released together + +**Build order enforced by Turbo**: core → hooks → ui (dependency chain) + +**React 19.1.2 exact pinning**: pnpm overrides lock all React packages to exact version + +**Tailwind CSS injection**: Auto-injected as JS constant via tsup define (no build step needed by consumers) + +**Changeset workflow**: pnpm changeset → pnpm version-packages → pnpm release + +**Trusted publishing**: OIDC-based npm publishing (no tokens) + +**Pre-commit**: Husky + lint-staged runs ESLint + Prettier on staged files + ## CRITICAL GOTCHAS +### Build & Dependencies - Always rebuild dependent packages after modifying core or hooks - Turbo build cache can skip changes - run `turbo build --force` if needed -- Changesets required for ALL version bumps (even patches) -- Pre-commit hooks fail if typecheck or lint fails - Workspace protocol: use `workspace:*` in package.json dependencies + +### Versioning & Release +- Changesets required for ALL version bumps (even patches) - **Unified versioning**: All packages must share exact same version - never version packages independently -- **Node.js requirement**: Minimum version 20.0.0 required for all environments +- Pre-commit hooks fail if typecheck or lint fails + +### Environment +- **Node.js requirement**: Minimum version 20.0.0 required +- **React version**: Do not change React dependencies; pnpm overrides enforce 19.1.2 +- **Package manager**: Do not use npm/yarn; only pnpm supported + +### Package Boundaries (FOR AGENTS) +- **Core must remain React-free** – do not import React or DOM APIs in `packages/core` +- **Hooks should not duplicate core logic** – call core clients instead of re-implementing HTTP +- **UI should not talk to the network directly** – always use hooks/core + +### Testing - One change in a package could break something in another package, so we want to make sure that all tests are passing across the packages before code gets pushed -- When stuck, ask clarifying questions + +### When Stuck +- Ask clarifying questions + +## ANTI-PATTERNS + +❌ Don't assume shared source directory (each package self-contained) +❌ Don't use API Extractor (listed but not actually used) +❌ Don't expect consistent build tools (core: tsup, hooks: tsc only, ui: tsup + tsc) +❌ Don't modify React version (exact 19.1.2 enforced via pnpm overrides) +❌ Don't use npm/yarn (only pnpm >= 9.0.0 supported) +❌ Don't break unified versioning (all packages versioned together) + +## MORE DETAIL PER PACKAGE + +- `packages/core/AGENTS.md` – API clients, schemas, auth +- `packages/hooks/AGENTS.md` – React hooks, providers +- `packages/ui/AGENTS.md` – UI components, styling, build order diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md index 92f8d2b..0a67e52 100644 --- a/packages/core/AGENTS.md +++ b/packages/core/AGENTS.md @@ -1,3 +1,5 @@ +# @youversion/platform-core + ## OVERVIEW Foundation package providing pure TypeScript API clients for YouVersion services with zero React dependencies. @@ -21,6 +23,40 @@ StorageStrategy.ts # Storage interface (SessionStorage, MemoryStorage) - `SignInWithYouVersionPKCE()`: PKCE auth flow function - `SessionStorage`, `MemoryStorage`: Storage strategies +## DOs / DON'Ts + +✅ Do: Keep this package **framework-agnostic** (no React, no DOM, no browser-only APIs) +✅ Do: Define all input/output types in `schemas/` using Zod; schemas are the single source of truth +✅ Do: Reuse `YouVersionAPI` base client for new service clients +✅ Do: Parse API responses with Zod schemas for validation + +❌ Don't: Import React, `window`, `document`, or browser storage APIs directly +❌ Don't: Bypass Zod validation for API responses +❌ Don't: Implement UI, hooks, or React state here + +## ADDING A NEW ENDPOINT OR CLIENT + +1. **Define types** in `schemas/` using Zod: + - Request payload schema + - Response schema +2. **Extend or add a client**: + - Prefer extending existing clients (e.g., `BibleClient`) when the endpoint logically belongs there + - Otherwise, create `xyz.ts` with a new `XyzClient` that composes `YouVersionAPI` +3. **Wire validation**: + - Parse API responses with the corresponding Zod schema + - Throw or return typed errors on validation failure +4. **Export from public API**: + - Expose the new client/types from the main entry file so consumers can import them +5. **Add tests**: + - Unit tests with MSW for mock responses + - Optional integration tests guarded by `INTEGRATION_TESTS=true` + +## HTTP & CONFIGURATION + +- HTTP client: Native `fetch` API +- Base client: `YouVersionAPI` handles base URL, headers, auth tokens +- All clients extend or compose `YouVersionAPI` for consistent HTTP behavior + ## CONVENTIONS - Schema-first: All types defined in schemas/*.ts using Zod - Zero React: Pure TypeScript, no React dependencies @@ -29,8 +65,11 @@ StorageStrategy.ts # Storage interface (SessionStorage, MemoryStorage) - Error handling: Zod validation for all API responses ## TESTING + +- Run tests: `pnpm --filter @youversion/platform-core test` - Framework: Vitest with Node environment - Mocking: MSW for API endpoints -- Integration: Set `INTEGRATION_TESTS=true` for real API tests +- Integration tests: + - Guarded by `INTEGRATION_TESTS=true` + - Only run in CI or when explicitly needed; default to mocked tests - Coverage: @vitest/coverage-v8 -- Files: Many test files covering all clients and auth diff --git a/packages/hooks/AGENTS.md b/packages/hooks/AGENTS.md index 45bb1a4..765fd79 100644 --- a/packages/hooks/AGENTS.md +++ b/packages/hooks/AGENTS.md @@ -1,7 +1,9 @@ # @youversion/platform-react-hooks ## OVERVIEW -React integration layer providing many data fetching hooks with 3 core providers: YouVersionProvider, YouVersionAuthProvider, and ReaderProvider. +React integration layer providing data fetching hooks with 3 core providers: YouVersionProvider, YouVersionAuthProvider, and ReaderProvider. + +**Depends on `@youversion/platform-core` for all API calls.** Hooks delegate to core clients; do not implement raw HTTP here. ## STRUCTURE - `use*.ts` - Data fetching hooks (useBook, useChapter, usePassage, useVersion, etc.) @@ -9,12 +11,44 @@ React integration layer providing many data fetching hooks with 3 core providers - `utility/` - Helper functions (useDebounce, extractTextFromHTML, extractVersesFromHTML) ## PUBLIC API -- Data fetching hooks: useBook, useChapter, usePassage, useVersion, etc. +- Data fetching hooks: useBook, useChapter, usePassage, useVersion, useVOTD, useVerse, useChapterNavigation, etc. - YouVersionProvider - Core SDK configuration - YouVersionAuthProvider - Authentication state - ReaderProvider - Reading session context - Utility functions exported from utility/index +## PROVIDERS + +- **YouVersionProvider** + - Holds core SDK configuration (API base URL, clients) + - Wrap this around your app before using any data hooks + +- **YouVersionAuthProvider** + - Manages authentication state (userInfo, tokens, isLoading, error) + - Auth hooks like `useYVAuth` depend on this provider + +- **ReaderProvider** + - Manages Bible reading session state (currentVersion, currentChapter, currentBook, currentVerse) + - Hooks like `useChapterNavigation` depend on this provider + +## DOs / DON'Ts + +✅ Do: Use `YouVersionProvider` for configuration and access that config in hooks +✅ Do: Wrap async data access in hooks rather than calling core clients directly in components +✅ Do: Keep hooks **UI-agnostic** (no JSX returned, no direct DOM manipulation) +✅ Do: Use the `useApiData` pattern for new data fetching hooks + +❌ Don't: Import components from `@youversion/platform-react-ui` +❌ Don't: Talk directly to `fetch`/HTTP; always use `@youversion/platform-core` +❌ Don't: Access `window.localStorage` directly for auth; rely on core's storage abstractions + +## DATA FETCHING PATTERN + +Hooks use a custom React Query-like pattern via `useApiData`: +- Returns `{ data, loading, error, refetch }` +- Provides caching and refetch capability +- New hooks should follow this same pattern + ## CONVENTIONS - Context and Provider in separate files - All contexts exported via context/index.ts @@ -22,7 +56,9 @@ React integration layer providing many data fetching hooks with 3 core providers - Build: tsc only ## TESTING -- Vitest with jsdom environment -- React Testing Library for component tests -- Many test files covering hooks and providers -- Mock API's live in `__tests__/mocks` + +- Run tests: `pnpm --filter @youversion/platform-react-hooks test` +- Framework: Vitest with jsdom environment +- React Testing Library for component/hook tests +- Mock APIs live in `__tests__/mocks` +- Use provider wrappers for tests so hooks see the same context as in the app diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md index 3a73567..0f1c548 100644 --- a/packages/ui/AGENTS.md +++ b/packages/ui/AGENTS.md @@ -1,4 +1,4 @@ -# AGENTS.md +# @youversion/platform-react-ui ## OVERVIEW Complete UI layer with many Bible components: BibleTextView, VerseOfTheDay, BibleReader, BibleChapterPicker, BibleVersionPicker, YouVersionAuthButton, BibleWidgetView, BibleAppLogoLockup @@ -13,7 +13,23 @@ src/index.ts # Entry point with style injection side effect ## PUBLIC API - Components exported from `src/components/` -- Re-exports: `YouVersionProvider`, `useYVAuth` from @youversion/platform-react-hooks +- Re-exports from `@youversion/platform-core`: + - `SignInWithYouVersionPermission`, `SignInWithYouVersionResult`, `YouVersionAPIUsers` + - `ApiConfig`, `AuthenticationState` types +- Re-exports from `@youversion/platform-react-hooks`: + - `YouVersionProvider`, `useYVAuth`, `UseYVAuthReturn` type + +## DOs / DON'Ts + +✅ Do: Use hooks from `@youversion/platform-react-hooks` for data; keep components thin +✅ Do: Use Radix UI primitives from `components/ui/` for low-level behaviors (modals, popovers, etc.) +✅ Do: Use Tailwind classes with the `yv:` prefix only +✅ Do: Use semantic theme tokens (`yv:text-muted-foreground`, `yv:bg-destructive`) instead of arbitrary colors + +❌ Don't: Make raw network requests from UI components +❌ Don't: Import from `@youversion/platform-core` directly (except re-exports in index.ts) +❌ Don't: Add global CSS files; all styling goes through Tailwind build and `injectStyles` +❌ Don't: Use unprefixed Tailwind classes (causes collisions in consumer apps) ## CONVENTIONS - React 19+ peer dependency @@ -30,6 +46,18 @@ src/index.ts # Entry point with style injection side effect - Light/dark mode via CSS variables (`[data-yv-sdk]`) - Use semantic theme tokens (`yv:text-muted-foreground`, `yv:bg-destructive`) instead of arbitrary color values +### Styling Usage Example + +```tsx +export function Example() { + return ( +
+ +
+ ); +} +``` + ## TESTING - Vitest + jsdom for unit tests (`*.test.tsx`) - Playwright for Storybook integration tests (`pnpm test:integration`) @@ -43,6 +71,11 @@ pnpm build:js # tsup bundling with __YV_STYLES__ injection pnpm build:types # tsc declarations ``` +From repo root, `pnpm build` runs Turbo which builds in order: +1. `@youversion/platform-core` +2. `@youversion/platform-react-hooks` +3. `@youversion/platform-react-ui` (build:css → build:js → build:types) + ## CRITICAL - **Side effect**: importing package injects styles automatically - Never skip build:css step (styles required for __YV_STYLES__ constant)