# IIIF Viewer Context Refactoring **Status:** Not started\ **Created:** 1 April 2026\ **Estimated effort:** 14-17 hours\ **Priority:** Medium ## Quick Start 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.wellcomecollection.org/request-for-comments-rfcs/086-item-viewer-refactor.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.