Adoption journeys

Executable paths through the docs — no monorepo clone required. Install packages from npm, follow linked pages in order.

Status key: ✅ completable from docs alone · ⚠️ minor gap (cross-link added or note required)

---

Start here (six core journeys)

1. Install → configure → search → display ✅

Goal: First photo search rendered in a React app.

Step	Page
1. Install packages	Installation
2. Set API keys (Vite env)	Installation — API keys
3. Quick search snippet	Quick Start
4. Wire hooks + UI	React hooks · UI components
5. (Optional) Copy starter	basic-react README

Exit: useMediaSearch returns items; grid or list renders thumbnails.

---

2. Pexels → Pixabay switch ✅

Goal: Swap provider by changing the client instance, not UI conditionals.

Step	Page
1. Canonical factory	Provider configuration
2. Env variable matrix	Provider configuration — env matrix
3. Pexels client details	PexelsMediaClient
4. Pixabay client + hotlinking	PixabayMediaClient
5. Side-by-side matrix	Provider comparison

Exit: App shell builds PexelsMediaClient or PixabayMediaClient; presentation uses capabilities only.

---

3. Capabilities → capability-driven UI ✅

Goal: Gate tabs and filters without if (provider === "pexels").

Step	Page
1. getCapabilities / types	Capabilities
2. React hook	useMediaCapabilities
3. Native hook	Native capabilities
4. Provider matrix reference	Compatibility — feature × provider

Exit: UI shows Curated tab only when caps.operations.curatedPhotos is true.

---

4. Filters → provider differences ✅

Goal: Apply filters safely per provider.

Step	Page
1. Filter types + validation	Filters
2. Photo/video filter matrix	Provider comparison
3. React hook filters	Hooks — photoFilters / videoFilters
4. Native filters	Native filters

Exit: Unsupported filters gated with caps.photoFilters.size (etc.); no UNSUPPORTED_FILTER at runtime.

---

5. Errors → MediaError handling ✅

Goal: Branch on code, status, and abort cancellation.

Step	Page
1. Error types reference	Errors
2. Decision tree + recipes	Error handling
3. Hook error narrowing	Error handling — hooks
4. Reliability context	Reliability

Exit: Handler distinguishes isAbortError, MediaError.code, and HTTP status.

---

6. React Native → Expo → native components ✅

Goal: Expo app with hooks and ui-native components.

Step	Page
1. Native overview	Native getting started
2. Install + peers	Native installation
3. MediaProvider	MediaProvider
4. Search hook	useMediaSearch
5. UI components	Native components
6. Full Expo walkthrough	Expo example
7. Troubleshooting	Native troubleshooting

Exit: Expo app runs; useMediaSearch + PhotoGrid render results.

---

Extended journeys (design checklist)

#	Journey	Entry	Status
7	Videos search	Pexels · useMediaVideos	✅
8	Pixabay-only setup	Pixabay (hotlinking §)	✅
9	Pexels curated	Provider configuration — curated recipe	✅
10	Migration 0.2 → 0.3	Migration guide	✅
11	Migration 0.3 → 1.0	1.0 migration guide	✅ (prep)

---

Journey audit summary (2026-08-09)

Journey	Status	Notes
1. Install → display	✅	Gate A fixed loading / trackView snippets
2. Provider switch	✅	Configuration page is canonical entry
3. Capabilities UI	✅	Web + native capability pages linked
4. Filters	✅	Comparison matrix + filters pages aligned
5. Errors	✅	Error handling decision tree complete
6. React Native / Expo	✅	Installation + expo-example + troubleshooting
7. Videos	✅	useMediaVideos documented web + native
8. Pixabay setup	✅	Hotlinking on pixabay.md; linked from configuration
9. Pexels curated	✅	App recipe documented (not SDK hook)
10. Migration	✅	0.2 → 0.3 guide present

Gaps: None blocking. DF-15 (Pixabay hotlink visibility) addressed via journey 2 + pixabay.md cross-links from Provider configuration.