> For the complete documentation index, see [llms.txt](https://docs.wellcomecollection.org/request-for-comments-rfcs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wellcomecollection.org/request-for-comments-rfcs/086-item-viewer-refactor.md). # RFC 086: IIIF Viewer Context Refactoring **Status:** Not started\ **Estimated effort:** 14-17 hours\ **Last modified:** 2026-04-14T13:30:00+00:00 ## Purpose This folder contains a comprehensive plan to refactor the IIIF Viewer context to eliminate code duplication and centralise derived state calculations. **Key principle:** Write automated tests BEFORE refactoring (test-first approach), then use manual testing for extra confidence. ## Table of Contents ### Understanding the Problem * [01 - Overview](/request-for-comments-rfcs/086-item-viewer-refactor/01-overview.md) - Problem statement, current architecture, and duplication examples * [02 - Normalisation Strategy](/request-for-comments-rfcs/086-item-viewer-refactor/02-normalisation-strategy.md) - Why and how we normalise variant implementations * [03 - Naming Conventions](/request-for-comments-rfcs/086-item-viewer-refactor/03-naming-conventions.md) - Crystal-clear boolean naming patterns ### Approach * [04 - Test-First Methodology](/request-for-comments-rfcs/086-item-viewer-refactor/04-test-first-approach.md) - **Write tests BEFORE refactoring** (automated tests are priority) * [05 - Feature Flag Strategy](/request-for-comments-rfcs/086-item-viewer-refactor/05-feature-flag-strategy.md) - Safe rollout with feature flags ### Implementation Phases * [06 - Phase 0: Type Audit](/request-for-comments-rfcs/086-item-viewer-refactor/06-phase-0-type-audit.md) (1-1.5 hours) - Do this first: Fix implicit `any` types & validate against official specs * [07 - Phase 1: Feature Flag Setup](/request-for-comments-rfcs/086-item-viewer-refactor/07-phase-1-feature-flag.md) (1 hour) * [08 - Phase 2: Split MainViewer Components](/request-for-comments-rfcs/086-item-viewer-refactor/08-phase-2-split-components.md) (3-4 hours) - Split before context refactoring * [09 - Phase 3: Canvas Data](/request-for-comments-rfcs/086-item-viewer-refactor/09-phase-3-canvas-data.md) (6-7 hours) - **Includes comprehensive automated tests** * [10 - Phase 4: Download Logic](/request-for-comments-rfcs/086-item-viewer-refactor/10-phase-4-download-logic.md) (2 hours) * [11 - Phase 5: Restriction Status](/request-for-comments-rfcs/086-item-viewer-refactor/11-phase-5-restriction-status.md) (1 hour) * [12 - Phase 6: Duplicate Index Calls](/request-for-comments-rfcs/086-item-viewer-refactor/12-phase-6-duplicate-calls.md) (30 mins) * [13 - Phase 7: Cleanup](/request-for-comments-rfcs/086-item-viewer-refactor/13-phase-7-cleanup.md) (1-2 hours) ### Reference * [13 - Migration Checklist](/request-for-comments-rfcs/086-item-viewer-refactor/13-migration-checklist.md) - Step-by-step checklist for each phase * [14 - Testing Strategy](/request-for-comments-rfcs/086-item-viewer-refactor/14-testing-strategy.md) - **Automated tests (priority) + manual testing checklist** * [15 - Risks & Success Metrics](/request-for-comments-rfcs/086-item-viewer-refactor/15-risks-and-success.md) - Risk mitigation and success criteria * [16 - Future Improvements](/request-for-comments-rfcs/086-item-viewer-refactor/16-future-improvements.md) - Post-refactor architectural improvements * [Testing Guide](/request-for-comments-rfcs/086-item-viewer-refactor/refactoring-iiif-viewer-context-testing.md) - Detailed test examples with TypeScript types ## Quick Navigation ### I want to understand the refactoring Start with [01-overview.md](/request-for-comments-rfcs/086-item-viewer-refactor/01-overview.md) ### I want to implement Phase 3 Read [09-phase-3-canvas-data.md](/request-for-comments-rfcs/086-item-viewer-refactor/09-phase-3-canvas-data.md) and [Testing Guide](/request-for-comments-rfcs/086-item-viewer-refactor/refactoring-iiif-viewer-context-testing.md) ### I want to see test examples Go to [Testing Guide](/request-for-comments-rfcs/086-item-viewer-refactor/refactoring-iiif-viewer-context-testing.md) for complete TypeScript test examples ### I want the testing checklist See [14-testing-strategy.md](/request-for-comments-rfcs/086-item-viewer-refactor/14-testing-strategy.md) for automated test requirements and manual testing checklist ## Key Principles 1. **Fix types first** - Audit and fix all types before refactoring (Phase 0) 2. **Automated tests BEFORE refactoring** - Build comprehensive test coverage first 3. **Feature flag everything** - Safe rollout with instant rollback capability 4. **Crystal-clear naming** - Use `is...`, `has...`, `can...`, `should...` patterns for booleans 5. **Test-first workflow** - Green to Green refactoring (tests pass before and after) 6. **Manual tests as backup** - Comprehensive checklist for extra confidence 7. **Context for shared state only** - Only add to context if used by 2+ components or likely to be needed soon 8. **Hooks for complex logic** - Extract to custom hooks for testability, even if only used once8. **Split components with drastically different modes** - See [Future Improvements](/request-for-comments-rfcs/086-item-viewer-refactor/16-future-improvements.md) for details ## Progress Tracking * [ ] Phase 0: Type Audit * [ ] Phase 1: Feature Flag Setup * [ ] Phase 2: Split MainViewer Components * [ ] Phase 3: Canvas Data (with automated tests) * [ ] Phase 4: Download Logic * [ ] Phase 5: Restriction Status * [ ] Phase 6: Duplicate Calls * [ ] Phase 7: Cleanup *** **Related Documentation:** * [AGENTS.md](https://github.com/wellcomecollection/docs/blob/main/AGENTS.md) - Development guidelines (British English, coding standards) * [.github/copilot-instructions.md](https://github.com/wellcomecollection/docs/blob/main/.github/copilot-instructions.md) - PR review guidelines