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 - Problem statement, current architecture, and duplication examples

• 02 - Normalisation Strategy - Why and how we normalise variant implementations

• 03 - Naming Conventions - Crystal-clear boolean naming patterns

Approach

• 04 - Test-First Methodology - Write tests BEFORE refactoring (automated tests are priority)

• 05 - Feature Flag Strategy - Safe rollout with feature flags

Implementation Phases

• 06 - Phase 0: Type Audit (1-1.5 hours) - Do this first: Fix implicit any types & validate against official specs

• 07 - Phase 1: Feature Flag Setup (1 hour)

• 08 - Phase 2: Split MainViewer Components (3-4 hours) - Split before context refactoring

• 09 - Phase 3: Canvas Data (6-7 hours) - Includes comprehensive automated tests

• 10 - Phase 4: Download Logic (2 hours)

• 11 - Phase 5: Restriction Status (1 hour)

• 12 - Phase 6: Duplicate Index Calls (30 mins)

• 13 - Phase 7: Cleanup (1-2 hours)

Reference

• 13 - Migration Checklist - Step-by-step checklist for each phase

• 14 - Testing Strategy - Automated tests (priority) + manual testing checklist

• 15 - Risks & Success Metrics - Risk mitigation and success criteria

• 16 - Future Improvements - Post-refactor architectural improvements

• Testing Guide - Detailed test examples with TypeScript types

Quick Navigation

I want to understand the refactoring

Start with 01-overview.md

I want to implement Phase 3

Read 09-phase-3-canvas-data.md and Testing Guide

I want to see test examples

Go to Testing Guide for complete TypeScript test examples

I want the testing checklist

See 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 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 - Development guidelines (British English, coding standards)

• .github/copilot-instructions.md - PR review guidelines