From 5cdb688903a8ba41fe78a2e5af41fd97cd1dec24 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 24 Sep 2025 22:31:33 +0000
Subject: [PATCH 1/4] Initial plan


From 748ceade9a29aec918f0899c662e118be78cee18 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 24 Sep 2025 22:35:43 +0000
Subject: [PATCH 2/4] Initial plan for contribution guidelines and supporting
 documentation

Co-authored-by: cubap <1119165+cubap@users.noreply.github.com>
---
 README.md            | 144 ++++++++++++++++++
 iiif-data-service.js | 349 +++++++++++++++++++++++++++++++++++++++++++
 index.html           |  20 +++
 message-handler.js   |  48 ++++++
 styles.css           | 102 +++++++++++++
 ui-manager.js        | 207 +++++++++++++++++++++++++
 viewer.js            |  92 ++++++++++++
 7 files changed, 962 insertions(+)
 create mode 100644 README.md
 create mode 100644 iiif-data-service.js
 create mode 100644 index.html
 create mode 100644 message-handler.js
 create mode 100644 styles.css
 create mode 100644 ui-manager.js
 create mode 100644 viewer.js

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..14c79b0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,144 @@
+# IIIF Page Viewer
+
+A lightweight IIIF (International Image Interoperability Framework) image viewing tool designed for inclusion as an iframe element in other documents. This viewer displays IIIF canvases with interactive annotation overlays.
+
+## JavaScript Architecture
+
+The JavaScript is organized into four main classes:
+
+### `IIIFDataService`
+
+- Handles all IIIF-related data fetching and parsing
+- Supports both IIIF v2 and v3 manifest formats
+- Manages coordinate parsing (XYWH format)
+- Includes error handling for failed requests
+
+### `UIManager`
+
+- Manages all user interface operations
+- Handles image rendering and annotation overlay creation
+- Manages tooltips, selection states, and user interactions
+- Includes accessibility features (ARIA labels, keyboard navigation)
+
+### `MessageHandler`
+
+- Manages communication with parent windows via postMessage API
+- Handles incoming canvas URL requests
+- Extensible for additional message types
+
+### `PageViewer`
+
+- Main orchestrator class that coordinates all components
+- Provides the public API for loading canvases
+- Manages application lifecycle and initialization
+
+## Features
+
+- **Responsive Design**: Scales properly within iframe containers
+- **Accessibility**: Full keyboard navigation and screen reader support
+- **Error Handling**: Graceful degradation with user-friendly error messages
+- **Loading States**: Visual feedback during data fetching
+- **Interactive Annotations**: Clickable overlays with hover tooltips
+- **Parent Communication**: Sends annotation selection events to parent window
+- **IIIF Image API Support**: Automatically detects and handles info.json responses
+
+## Usage
+
+### As an iframe
+
+```html
+<iframe src="view-full-page-iframe.html" width="800" height="600"></iframe>
+```
+
+### Communication with Parent Window
+
+The viewer supports multiple ways to load IIIF content via messages from the parent window:
+
+#### Direct Canvas URL
+
+```javascript
+// Send direct canvas URL to iframe
+iframe.contentWindow.postMessage({
+    type: "CANVAS_URL",
+    canvasUrl: "https://example.com/path/to/canvas/data"
+}, "*");
+```
+
+#### Manifest with Canvas Reference
+
+```javascript
+// Send manifest URL with canvas fragment identifier
+iframe.contentWindow.postMessage({
+    type: "CANVAS_URL",
+    canvasUrl: "https://example.com/manifest.json#canvas-id"
+}, "*");
+
+// Or use separate manifest and canvas ID
+iframe.contentWindow.postMessage({
+    type: "MANIFEST_CANVAS",
+    manifestUrl: "https://example.com/manifest.json",
+    canvasId: "canvas-id"  // Optional - uses first canvas if omitted
+}, "*");
+```
+
+#### Listen for Events
+
+```javascript
+// Listen for annotation selection events
+window.addEventListener("message", (event) => {
+    if (event.data.type === "RETURN_LINE_ID") {
+        console.log("Selected annotation:", event.data.lineid, event.data.lineIndex);
+    }
+});
+```
+
+### Direct Canvas Loading
+
+You can also load a canvas directly via URL parameter:
+
+```text
+view-full-page-iframe.html?canvas=https://example.com/path/to/canvas/manifest
+```
+
+The canvas parameter supports:
+
+- Direct canvas data URLs
+- Manifest URLs (uses first canvas)
+- Manifest URLs with fragment identifiers: `manifest.json#canvas-id`
+
+### IIIF Image API Support
+
+The viewer automatically detects when image URLs point to IIIF Image API info.json files and constructs optimized image URLs:
+
+- **Automatic Detection**: Checks if image URLs return JSON with IIIF Image API info
+- **Size Optimization**: Calculates optimal image dimensions while maintaining aspect ratio
+- **Profile Compliance**: Respects size limitations from IIIF Image API profiles
+- **Fallback Handling**: Falls back to original URLs if IIIF Image API processing fails
+
+Example flow:
+
+1. Canvas references image: `https://example.com/iiif/image123`
+2. Viewer detects this returns info.json with IIIF Image API data
+3. Constructs optimized URL: `https://example.com/iiif/image123/full/800,600/0/default.jpg`
+
+## Browser Support
+
+- Modern browsers with ES6+ support
+- Fetch API support required
+- PostMessage API for iframe communication
+
+## IIIF Compatibility
+
+- **IIIF Presentation API** v2.x and v3.x
+- **IIIF Image API** v2.x and v3.x (automatic info.json handling)
+- Supports standard XYWH coordinate selectors
+- Automatic image URL construction from IIIF Image API info.json responses
+
+## Development
+
+The modular architecture makes it easy to:
+
+- **Extend functionality**: Add new classes or methods
+- **Modify styling**: Edit `styles.css` for visual changes
+- **Add message types**: Extend `MessageHandler` for new communication patterns
+- **Customize UI**: Modify `UIManager` for different interaction patterns
diff --git a/iiif-data-service.js b/iiif-data-service.js
new file mode 100644
index 0000000..8bd9622
--- /dev/null
+++ b/iiif-data-service.js
@@ -0,0 +1,349 @@
+/**
+ * IIIF Data Service - Handles all IIIF-related data fetching and parsing
+ * Supports IIIF Presentation API v2/v3 and IIIF Image API v2/v3
+ * 
+ * @author Priyal Patel @mepripri
+ * @author Patrick Cuba @cubap
+ */
+export class IIIFDataService {
+    /**
+     * Parse XYWH coordinate string into object
+     * @param {string} target - XYWH coordinate string
+     * @returns {Object} Parsed coordinates {x, y, w, h}
+     */
+    parseXYWH(target) {
+        const xywh = target.replace("xywh=pixel:", "").split(",").map(Number)
+        return { x: xywh[0], y: xywh[1], w: xywh[2], h: xywh[3] }
+    }
+
+    /**
+     * Fetch and parse IIIF canvas data with annotations
+     * @param {string} canvasUrl - URL to the IIIF canvas or manifest containing the canvas
+     * @returns {Promise<Object|null>} Canvas data with image URL, annotations, and dimensions
+     */
+    async fetchCanvasData(canvasUrl) {
+        try {
+            const response = await fetch(canvasUrl)
+            if (!response.ok) {
+                throw new Error(`Failed to fetch data from URL: ${response.status}`)
+            }
+
+            const data = await response.json()
+            
+            // Check if this is manifest data that contains canvases
+            if (this.isManifestData(data)) {
+                return await this.extractCanvasFromManifest(data, canvasUrl)
+            }
+            
+            // Check if this is direct canvas data with a target
+            if (data.target) {
+                return await this.processCanvasData(data)
+            }
+            
+            // If we have items but no target, this might be a canvas without annotations
+            if (data.items || data.images) {
+                return await this.processDirectCanvasData(data)
+            }
+            
+            throw new Error("Unrecognized data format - not a valid IIIF manifest or canvas")
+            
+        } catch (error) {
+            console.error("Error fetching IIIF canvas data:", error)
+            throw error
+        }
+    }
+
+    /**
+     * Check if the data represents a IIIF manifest
+     * @param {Object} data - The fetched JSON data
+     * @returns {boolean} True if this appears to be manifest data
+     */
+    isManifestData(data) {
+        // IIIF v3 manifest indicators
+        if (data.type === "Manifest" || data["@type"] === "sc:Manifest") {
+            return true
+        }
+        
+        // Check for sequences (IIIF v2) or items with canvases (IIIF v3)
+        return !!(data.sequences || (data.items && Array.isArray(data.items)))
+    }
+
+    /**
+     * Extract canvas data from a IIIF manifest
+     * @param {Object} manifestData - The manifest data
+     * @param {string} originalUrl - The original URL (may contain canvas fragment)
+     * @returns {Promise<Object>} Canvas data
+     */
+    async extractCanvasFromManifest(manifestData, originalUrl) {
+        let targetCanvas = null
+        
+        // Check if URL contains a canvas fragment identifier
+        const urlParts = originalUrl.split('#')
+        const canvasId = urlParts.length > 1 ? urlParts[1] : null
+        
+        // IIIF v3 format
+        if (manifestData.items) {
+            if (canvasId) {
+                // Find specific canvas by ID
+                targetCanvas = manifestData.items.find(item => 
+                    item.id === canvasId || 
+                    item.id.endsWith(`#${canvasId}`) ||
+                    item.id.endsWith(`/${canvasId}`)
+                )
+            }
+            targetCanvas ??= manifestData.items[0]
+        }
+        // IIIF v2 format
+        else if (manifestData.sequences?.[0]?.canvases) {
+            const canvases = manifestData.sequences[0].canvases
+            if (canvasId) {
+                targetCanvas = canvases.find(canvas => 
+                    canvas["@id"] === canvasId || 
+                    canvas["@id"].endsWith(`#${canvasId}`) ||
+                    canvas["@id"].endsWith(`/${canvasId}`)
+                )
+            }
+            targetCanvas ??= canvases[0]
+        }
+        
+        if (!targetCanvas) {
+            throw new Error("No canvas found in manifest")
+        }
+        
+        // Process the canvas data directly
+        return await this.processDirectCanvasData(targetCanvas)
+    }
+
+    /**
+     * Process canvas data that has annotation references
+     * @param {Object} data - Canvas data with target reference
+     * @returns {Promise<Object>} Processed canvas data
+     */
+    async processCanvasData(data) {
+        const target = await fetch(data.target)
+        
+        if (!target.ok) {
+            throw new Error(`Failed to fetch target data: ${target.status}`)
+        }
+
+        const targetData = await target.json()
+        const canvasInfo = await this.extractImageInfo(targetData)
+        
+        // Fetch annotation data
+        const annotations = await Promise.all(
+            data.items.map(async (anno) => {
+                try {
+                    const line = await fetch(anno.id)
+                    if (!line.ok) return null
+                    
+                    const lineData = await line.json()
+                    return {
+                        target: lineData?.target?.selector?.value ?? lineData?.target,
+                        text: lineData?.body?.value ?? "",
+                        lineid: lineData?.id?.split("/")?.pop()
+                    }
+                } catch (error) {
+                    console.warn(`Failed to fetch annotation ${anno.id}:`, error)
+                    return null
+                }
+            })
+        )
+
+        const validAnnotations = annotations.filter(anno => anno !== null)
+        
+        return { ...canvasInfo, annotations: validAnnotations }
+    }
+
+    /**
+     * Process direct canvas data (from manifest or direct canvas)
+     * @param {Object} canvasData - Direct canvas data
+     * @returns {Promise<Object>} Processed canvas data
+     */
+    async processDirectCanvasData(canvasData) {
+        const canvasInfo = await this.extractImageInfo(canvasData)
+        
+        // Look for annotations in the canvas
+        let annotations = []
+        
+        // IIIF v3 annotations
+        if (canvasData.annotations) {
+            // This would require additional processing for annotation pages
+            console.log("Canvas has annotations - additional processing may be needed")
+        }
+        
+        // For now, return with empty annotations if no annotation target is found
+        return { ...canvasInfo, annotations }
+    }
+
+    /**
+     * Extract image information from canvas data
+     * @param {Object} canvasData - Canvas data
+     * @returns {Promise<Object>} Image URL, width, and height
+     */
+    async extractImageInfo(canvasData) {
+        // Support both IIIF v2 and v3 formats
+        const imgUrl = canvasData?.items?.[0]?.items?.[0]?.body?.id ?? 
+                       canvasData?.images?.[0]?.resource?.["@id"] ??
+                       canvasData?.images?.[0]?.resource?.id
+                      
+        const imgWidth = canvasData?.width
+        const imgHeight = canvasData?.height
+
+        if (!imgUrl || !imgWidth || !imgHeight) {
+            throw new Error("Missing required image data in IIIF canvas")
+        }
+
+        // Check if the image URL points to an info.json (IIIF Image API)
+        const processedImageUrl = await this.processIIIFImageUrl(imgUrl, imgWidth, imgHeight)
+
+        return { imgUrl: processedImageUrl, imgWidth, imgHeight }
+    }
+
+    /**
+     * Process IIIF Image URL and handle info.json responses
+     * @param {string} imgUrl - Original image URL
+     * @param {number} maxWidth - Maximum width from canvas
+     * @param {number} maxHeight - Maximum height from canvas
+     * @returns {Promise<string>} Processed image URL
+     */
+    async processIIIFImageUrl(imgUrl, maxWidth, maxHeight) {
+        try {
+            // First, try to fetch the URL to see if it returns info.json
+            const response = await fetch(imgUrl)
+            
+            if (!response.ok) {
+                // If fetch fails, return original URL (might be a direct image)
+                return imgUrl
+            }
+
+            const contentType = response.headers.get('content-type')
+            
+            // Check if response is JSON (indicating info.json)
+            if (contentType?.includes('application/json') || contentType?.includes('application/ld+json')) {
+                const infoData = await response.json()
+                
+                // Validate this is a IIIF Image API info.json
+                if (this.isIIIFImageInfo(infoData)) {
+                    return this.constructIIIFImageUrl(infoData, maxWidth, maxHeight)
+                }
+            }
+            
+            // If it's not JSON or not a valid info.json, return original URL
+            return imgUrl
+            
+        } catch (error) {
+            console.warn('Error processing IIIF image URL:', error)
+            // Fallback to original URL if processing fails
+            return imgUrl
+        }
+    }
+
+    /**
+     * Check if the data is a valid IIIF Image API info.json
+     * @param {Object} data - JSON data to validate
+     * @returns {boolean} True if valid IIIF Image API info
+     */
+    isIIIFImageInfo(data) {
+        // Check for IIIF Image API v2 or v3 indicators
+        return (
+            // IIIF Image API v3
+            (data.type === "ImageService3" || data["@type"] === "ImageService3") ||
+            // IIIF Image API v2
+            (data["@context"] && (
+                data["@context"].includes("iiif.io/api/image/2") ||
+                data["@context"].includes("iiif.io/api/image/3")
+            )) ||
+            // Basic validation - has required properties
+            (data.width && data.height && data["@id"])
+        )
+    }
+
+    /**
+     * Construct a IIIF Image API URL from info.json data
+     * @param {Object} infoData - IIIF Image API info.json data
+     * @param {number} maxWidth - Maximum width constraint
+     * @param {number} maxHeight - Maximum height constraint
+     * @returns {string} Constructed IIIF Image URL
+     */
+    constructIIIFImageUrl(infoData, maxWidth, maxHeight) {
+        const baseUrl = infoData["@id"] || infoData.id
+        const imageWidth = infoData.width
+        const imageHeight = infoData.height
+        
+        if (!baseUrl) {
+            throw new Error("No base URL found in IIIF Image API info")
+        }
+
+        // Calculate optimal size while maintaining aspect ratio
+        const aspectRatio = imageWidth / imageHeight
+        let targetWidth = Math.min(maxWidth, imageWidth)
+        let targetHeight = Math.min(maxHeight, imageHeight)
+        
+        // Adjust to maintain aspect ratio
+        if (targetWidth / aspectRatio > targetHeight) {
+            targetWidth = Math.floor(targetHeight * aspectRatio)
+        } else {
+            targetHeight = Math.floor(targetWidth / aspectRatio)
+        }
+
+        // Check supported sizes and profiles for optimal parameters
+        const sizeParam = this.getBestSizeParameter(infoData, targetWidth, targetHeight)
+        
+        // Construct IIIF Image API URL: {baseUrl}/{region}/{size}/{rotation}/{quality}.{format}
+        // Using full region, calculated size, no rotation, default quality, jpg format
+        const imageUrl = `${baseUrl}/full/${sizeParam}/0/default.jpg`
+        
+        console.log(`Constructed IIIF Image URL: ${imageUrl}`)
+        return imageUrl
+    }
+
+    /**
+     * Determine the best size parameter for IIIF Image API URL
+     * @param {Object} infoData - IIIF Image API info.json data
+     * @param {number} targetWidth - Target width
+     * @param {number} targetHeight - Target height
+     * @returns {string} Size parameter for IIIF URL
+     */
+    getBestSizeParameter(infoData, targetWidth, targetHeight) {
+        // Check if specific sizes are available
+        if (infoData.sizes && Array.isArray(infoData.sizes)) {
+            // Find the closest available size
+            const availableSize = infoData.sizes.find(size => 
+                size.width >= targetWidth && size.height >= targetHeight
+            ) ?? infoData.sizes[infoData.sizes.length - 1] // fallback to largest
+            
+            if (availableSize) {
+                return `${availableSize.width},${availableSize.height}`
+            }
+        }
+        
+        // Check profile/compliance for size restrictions
+        const maxSize = this.getMaxAllowedSize(infoData)
+        if (maxSize) {
+            targetWidth = Math.min(targetWidth, maxSize.width)
+            targetHeight = Math.min(targetHeight, maxSize.height)
+        }
+        
+        // Use width,height format for explicit sizing
+        return `${targetWidth},${targetHeight}`
+    }
+
+    /**
+     * Get maximum allowed size from IIIF Image API profile
+     * @param {Object} infoData - IIIF Image API info.json data
+     * @returns {Object|null} Maximum size object or null
+     */
+    getMaxAllowedSize(infoData) {
+        if (!infoData.profile || !Array.isArray(infoData.profile)) return null
+        
+        for (const profileItem of infoData.profile) {
+            if (typeof profileItem === 'object' && profileItem.maxWidth && profileItem.maxHeight) {
+                return {
+                    width: profileItem.maxWidth,
+                    height: profileItem.maxHeight
+                }
+            }
+        }
+        return null
+    }
+}
diff --git a/index.html b/index.html
new file mode 100644
index 0000000..0ec949f
--- /dev/null
+++ b/index.html
@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>IIIF Page Viewer</title>
+    <meta name="description" content="IIIF image viewing tool for displaying canvases with annotation overlays">
+    <link rel="stylesheet" href="styles.css">
+    <script type="module" src="viewer.js"></script>
+</head>
+<body>
+    <main role="main">
+        <section id="imageContainer" aria-label="IIIF Canvas Viewer">
+            <div class="loading" role="status" aria-live="polite">
+                Loading viewer...
+            </div>
+        </section>
+    </main>
+</body>
+</html>
diff --git a/message-handler.js b/message-handler.js
new file mode 100644
index 0000000..02c854b
--- /dev/null
+++ b/message-handler.js
@@ -0,0 +1,48 @@
+/**
+ * Message Handler - Manages communication with parent window
+ * Handles postMessage API communication for iframe integration
+ * 
+ * @author Priyal Patel @mepripri
+ * @author Patrick Cuba @cubap
+ */
+export class MessageHandler {
+    constructor(pageViewer) {
+        this.pageViewer = pageViewer
+        this.setupMessageListener()
+    }
+
+    /**
+     * Set up message listener for parent window communication
+     */
+    setupMessageListener() {
+        window.addEventListener("message", (event) => {
+            this.handleMessage(event)
+        })
+    }
+
+    /**
+     * Handle incoming messages from parent window
+     * @param {MessageEvent} event - The message event
+     */
+    handleMessage(event) {
+        if (!event.data?.type) return
+
+        switch (event.data.type) {
+            case "CANVAS_URL":
+                if (event.data.canvasUrl) {
+                    this.pageViewer.loadCanvas(event.data.canvasUrl)
+                }
+                break
+            case "MANIFEST_CANVAS":
+                if (event.data.manifestUrl) {
+                    this.pageViewer.loadCanvasFromManifest(
+                        event.data.manifestUrl, 
+                        event.data.canvasId
+                    )
+                }
+                break
+            default:
+                console.warn("Unknown message type:", event.data.type)
+        }
+    }
+}
diff --git a/styles.css b/styles.css
new file mode 100644
index 0000000..b4b5414
--- /dev/null
+++ b/styles.css
@@ -0,0 +1,102 @@
+/* IIIF Page Viewer Styles */
+
+/* Main container for the image viewer */
+#imageContainer {
+    position: relative;
+    display: inline-block;
+    max-width: 100%;
+    background-image: url(https://t-pen.org/TPEN/images/loading2.gif);
+    background-repeat: no-repeat;
+    background-position: center;
+    min-height: 200px;
+    width: 100%;
+    pointer-events: none;
+}
+
+/* The main canvas image */
+#canvasImage {
+    width: 100%;
+    height: auto;
+    display: block;
+}
+
+/* Overlay boxes for annotations */
+.overlayBox {
+    position: absolute;
+    border: 1px solid white;
+    pointer-events: auto;
+    box-sizing: border-box;
+    cursor: pointer;
+    transition: box-shadow 0.15s ease, border-color 0.15s ease;
+    border-radius: 2px;
+}
+
+/* Active/clicked state for overlay boxes */
+.overlayBox.clicked {
+    border-color: #ff6f3d;
+    border-width: 3px;
+    box-shadow: 0 0 12px rgba(255, 255, 255, 0.8);
+    z-index: 10;
+}
+
+/* Hover state for overlay boxes */
+.overlayBox:hover {
+    border-color: rgba(255, 255, 255, 0.8);
+    box-shadow: 0 0 8px rgba(255, 255, 255, 0.5);
+}
+
+/* Tooltip styling */
+.tooltip {
+    background-color: #ff6f3d;
+    color: white;
+    padding: 4px 8px;
+    border-radius: 4px;
+    position: absolute;
+    bottom: -25px;
+    left: 50%;
+    transform: translateX(-50%);
+    white-space: nowrap;
+    font-size: 12px;
+    pointer-events: none;
+    opacity: 0.9;
+    z-index: 5;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
+}
+
+/* Error states */
+.error-message {
+    color: #d32f2f;
+    background-color: #ffebee;
+    padding: 12px;
+    border-radius: 4px;
+    border: 1px solid #e57373;
+    text-align: center;
+    font-family: Arial, sans-serif;
+}
+
+/* Loading states */
+.loading {
+    text-align: center;
+    padding: 20px;
+    font-family: Arial, sans-serif;
+    color: #666;
+}
+
+/* Accessibility improvements */
+.sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+}
+
+/* Focus styles for accessibility */
+.overlayBox:focus {
+    outline: 2px solid #ff6f3d;
+    outline-offset: 2px;
+}
diff --git a/ui-manager.js b/ui-manager.js
new file mode 100644
index 0000000..6a7d324
--- /dev/null
+++ b/ui-manager.js
@@ -0,0 +1,207 @@
+import { IIIFDataService } from './iiif-data-service.js'
+
+/**
+ * UI Manager - Handles all user interface operations
+ * Manages DOM manipulation, event handling, and user interactions
+ * 
+ * @author Priyal Patel @mepripri
+ * @author Patrick Cuba @cubap
+ */
+export class UIManager {
+    constructor(containerId = 'imageContainer') {
+        this.container = document.getElementById(containerId)
+        this.currentAnnotations = []
+        this.eventHandlers = new Map()
+        this.dataService = new IIIFDataService() // For coordinate parsing
+    }
+
+    /**
+     * Display error message to user
+     * @param {string} message - Error message to display
+     */
+    showError(message) {
+        this.container.innerHTML = `
+            <div class="error-message" role="alert">
+                <strong>Error:</strong> ${message}
+            </div>
+        `
+        this.container.style.backgroundImage = "none"
+    }
+
+    /**
+     * Display loading state
+     * @param {string} message - Loading message
+     */
+    showLoading(message = "Loading canvas data...") {
+        this.container.innerHTML = `
+            <div class="loading" role="status" aria-live="polite">
+                ${message}
+            </div>
+        `
+    }
+
+    /**
+     * Render the main image
+     * @param {string} imgUrl - URL of the image to display
+     * @returns {Promise<HTMLImageElement>} Promise that resolves when image loads
+     */
+    renderImage(imgUrl) {
+        return new Promise((resolve, reject) => {
+            this.container.innerHTML = `
+                <img id="canvasImage" src="${imgUrl}" alt="IIIF Canvas Image" />
+            `
+            this.container.style.backgroundImage = "none"
+            
+            const img = document.getElementById("canvasImage")
+            img.onload = () => resolve(img)
+            img.onerror = () => reject(new Error("Failed to load image"))
+        })
+    }
+
+    /**
+     * Create and render annotation overlays
+     * @param {Array} annotations - Array of annotation objects
+     * @param {number} imgWidth - Original image width
+     * @param {number} imgHeight - Original image height
+     */
+    renderAnnotations(annotations, imgWidth, imgHeight) {
+        this.currentAnnotations = annotations
+        
+        annotations.forEach((anno, index) => {
+            if (!anno.target) return
+
+            const { x, y, w, h } = this.dataService.parseXYWH(anno.target)
+            
+            // Calculate percentages for responsive positioning
+            const left = (x / imgWidth) * 100
+            const top = (y / imgHeight) * 100
+            const width = (w / imgWidth) * 100
+            const height = (h / imgHeight) * 100
+
+            const box = this.createAnnotationBox(anno, index, left, top, width, height)
+            this.container.appendChild(box)
+        })
+    }
+
+    /**
+     * Create an individual annotation overlay box
+     * @param {Object} anno - Annotation data
+     * @param {number} index - Annotation index
+     * @param {number} left - Left position percentage
+     * @param {number} top - Top position percentage
+     * @param {number} width - Width percentage
+     * @param {number} height - Height percentage
+     * @returns {HTMLElement} The created overlay box element
+     */
+    createAnnotationBox(anno, index, left, top, width, height) {
+        const box = document.createElement("div")
+        box.className = "overlayBox"
+        box.style.left = `${left}%`
+        box.style.top = `${top}%`
+        box.style.width = `${width}%`
+        box.style.height = `${height}%`
+        box.title = anno.text || "Annotation"
+        box.dataset.lineserverid = anno.lineid
+        box.dataset.lineid = index
+        
+        // Add accessibility attributes
+        box.setAttribute('role', 'button')
+        box.setAttribute('tabindex', '0')
+        box.setAttribute('aria-label', `Annotation ${index + 1}: ${anno.text || 'No text available'}`)
+
+        // Add event listeners
+        this.attachAnnotationEvents(box, anno, index)
+
+        return box
+    }
+
+    /**
+     * Attach event listeners to annotation box
+     * @param {HTMLElement} box - The annotation box element
+     * @param {Object} anno - Annotation data
+     * @param {number} index - Annotation index
+     */
+    attachAnnotationEvents(box, anno, index) {
+        // Mouse enter - show tooltip
+        box.addEventListener("mouseenter", () => {
+            this.showTooltip(box, anno.text)
+        })
+
+        // Mouse leave - hide tooltip
+        box.addEventListener("mouseleave", () => {
+            this.hideTooltip(box)
+        })
+
+        // Click handler
+        const clickHandler = () => {
+            this.selectAnnotation(box, anno.lineid, index)
+        }
+
+        box.addEventListener("click", clickHandler)
+        
+        // Keyboard support
+        box.addEventListener("keydown", (event) => {
+            if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault()
+                clickHandler()
+            }
+        })
+    }
+
+    /**
+     * Show tooltip for annotation
+     * @param {HTMLElement} box - The annotation box
+     * @param {string} text - Tooltip text
+     */
+    showTooltip(box, text) {
+        if (!text || box.querySelector(".tooltip")) return
+        
+        const tooltip = document.createElement("div")
+        tooltip.className = "tooltip"
+        tooltip.textContent = text
+        tooltip.setAttribute('role', 'tooltip')
+        box.appendChild(tooltip)
+    }
+
+    /**
+     * Hide tooltip for annotation
+     * @param {HTMLElement} box - The annotation box
+     */
+    hideTooltip(box) {
+        const tooltip = box.querySelector(".tooltip")
+        tooltip?.remove()
+    }
+
+    /**
+     * Select an annotation and notify parent window
+     * @param {HTMLElement} box - The clicked annotation box
+     * @param {string} lineid - Line ID
+     * @param {number} index - Line index
+     */
+    selectAnnotation(box, lineid, index) {
+        // Remove previous selection
+        document.querySelectorAll('.overlayBox.clicked').forEach(el => {
+            el.classList.remove('clicked')
+            el.setAttribute('aria-selected', 'false')
+        })
+        
+        // Add selection to current box
+        box.classList.add('clicked')
+        box.setAttribute('aria-selected', 'true')
+        
+        // Notify parent window
+        window.parent?.postMessage({
+            type: "RETURN_LINE_ID",
+            lineid,
+            lineIndex: index
+        }, "*")
+    }
+
+    /**
+     * Clear all content and reset container
+     */
+    clear() {
+        this.container.innerHTML = ""
+        this.currentAnnotations = []
+    }
+}
diff --git a/viewer.js b/viewer.js
new file mode 100644
index 0000000..5dbc952
--- /dev/null
+++ b/viewer.js
@@ -0,0 +1,92 @@
+/**
+ * IIIF Page Viewer - Main Module
+ * 
+ * A modular IIIF image viewer that supports both Presentation API (v2/v3) 
+ * and Image API (v2/v3) standards. This main module coordinates between
+ * data services, UI management, and message handling.
+ * 
+ * @author Priyal Patel @mepripri
+ * @author Patrick Cuba @cubap
+ * @version 2.0.0
+ */
+
+import { IIIFDataService } from './iiif-data-service.js'
+import { UIManager } from './ui-manager.js'
+import { MessageHandler } from './message-handler.js'
+
+/**
+ * Main PageViewer class that coordinates IIIF data loading and UI updates
+ */
+class PageViewer {
+    constructor(containerId = 'imageContainer') {
+        this.dataService = new IIIFDataService()
+        this.uiManager = new UIManager(containerId)
+        this.messageHandler = new MessageHandler(this)
+    }
+
+    /**
+     * Load and display a IIIF canvas
+     * @param {string} canvasUrl - URL to the IIIF canvas or manifest containing the canvas
+     */
+    async loadCanvas(canvasUrl) {
+        if (!canvasUrl) {
+            console.warn("No canvas URL provided")
+            this.uiManager.showError("No canvas URL provided")
+            return
+        }
+
+        try {
+            this.uiManager.showLoading("Loading canvas data...")
+            
+            const canvasData = await this.dataService.fetchCanvasData(canvasUrl)
+            if (!canvasData) {
+                throw new Error("No canvas data received")
+            }
+
+            const { imgUrl, annotations, imgWidth, imgHeight } = canvasData
+            
+            // Load the image first
+            await this.uiManager.renderImage(imgUrl)
+            
+            // Then render annotations
+            this.uiManager.renderAnnotations(annotations, imgWidth, imgHeight)
+            
+        } catch (error) {
+            console.error("Error loading canvas:", error)
+            this.uiManager.showError(`Failed to load canvas: ${error.message}`)
+        }
+    }
+
+    /**
+     * Load a specific canvas from a manifest
+     * @param {string} manifestUrl - URL to the IIIF manifest
+     * @param {string} canvasId - ID of the specific canvas within the manifest
+     */
+    async loadCanvasFromManifest(manifestUrl, canvasId) {
+        const canvasUrl = canvasId ? `${manifestUrl}#${canvasId}` : manifestUrl
+        await this.loadCanvas(canvasUrl)
+    }
+
+    /**
+     * Initialize the page viewer
+     */
+    init() {
+        // Check if canvas URL is provided via URL parameters or other means
+        const urlParams = new URLSearchParams(window.location.search)
+        const canvasUrl = urlParams.get('canvas')
+        
+        if (canvasUrl) {
+            this.loadCanvas(canvasUrl)
+        } else {
+            this.uiManager.showLoading("Waiting for canvas URL from parent window...")
+        }
+    }
+}
+
+// Initialize the page viewer when the DOM is loaded
+document.addEventListener('DOMContentLoaded', () => {
+    const viewer = new PageViewer()
+    viewer.init()
+})
+
+export { PageViewer }

From 44486cf98154f60fae2b8c13ff373b23e4977564 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 24 Sep 2025 22:42:28 +0000
Subject: [PATCH 3/4] Add comprehensive contribution guidelines and supporting
 documentation

Co-authored-by: cubap <1119165+cubap@users.noreply.github.com>
---
 .github/ISSUE_TEMPLATE/bug_report.yml         | 105 +++++
 .github/ISSUE_TEMPLATE/config.yml             |  14 +
 .github/ISSUE_TEMPLATE/feature_request.yml    | 131 +++++++
 .github/ISSUE_TEMPLATE/iiif_compatibility.yml | 144 +++++++
 .github/PULL_REQUEST_TEMPLATE.md              | 122 ++++++
 .gitignore                                    | 113 ++++++
 CHANGELOG.md                                  |  95 +++++
 CODE_OF_CONDUCT.md                            |  93 +++++
 CONTRIBUTING.md                               | 197 ++++++++++
 COPILOT.md                                    | 237 +++++++++++
 DEVELOPMENT.md                                | 370 ++++++++++++++++++
 LICENSE                                       |  21 +
 README.md                                     |  41 +-
 SECURITY.md                                   | 178 +++++++++
 package.json                                  |  80 ++++
 15 files changed, 1940 insertions(+), 1 deletion(-)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml
 create mode 100644 .github/ISSUE_TEMPLATE/iiif_compatibility.yml
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .gitignore
 create mode 100644 CHANGELOG.md
 create mode 100644 CODE_OF_CONDUCT.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 COPILOT.md
 create mode 100644 DEVELOPMENT.md
 create mode 100644 LICENSE
 create mode 100644 SECURITY.md
 create mode 100644 package.json

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..b5fb7f7
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,105 @@
+name: Bug Report
+description: Report a bug or issue with the IIIF Page Viewer
+title: "[Bug]: "
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the following information to help us understand and reproduce the issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe what happened and what you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Please provide detailed steps to reproduce the issue.
+      placeholder: |
+        1. Go to '...'
+        2. Load IIIF manifest '...'
+        3. Click on '...'
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: iiif-manifest
+    attributes:
+      label: IIIF Manifest URL
+      description: If the issue is related to a specific IIIF manifest, please provide the URL.
+      placeholder: https://example.com/iiif/manifest.json
+    validations:
+      required: false
+
+  - type: dropdown
+    id: browser
+    attributes:
+      label: Browser
+      description: Which browser are you using?
+      options:
+        - Chrome
+        - Firefox
+        - Safari
+        - Edge
+        - Other (specify in additional context)
+    validations:
+      required: true
+
+  - type: input
+    id: browser-version
+    attributes:
+      label: Browser Version
+      description: What version of the browser are you using?
+      placeholder: e.g., Chrome 118.0.5993.88
+    validations:
+      required: true
+
+  - type: dropdown
+    id: device
+    attributes:
+      label: Device Type
+      description: What type of device are you using?
+      options:
+        - Desktop/Laptop
+        - Mobile Phone
+        - Tablet
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: console-errors
+    attributes:
+      label: Console Errors
+      description: Please check the browser's developer console for errors and paste them here.
+      placeholder: |
+        Error: Failed to fetch manifest
+        at IIIFDataService.fetchCanvasData (iiif-data-service.js:45)
+      render: shell
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here, including screenshots if helpful.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: testing
+    attributes:
+      label: Testing Checklist
+      description: Have you tested this issue?
+      options:
+        - label: I have tested this in multiple browsers
+        - label: I have checked the browser console for errors
+        - label: I have verified the IIIF manifest is valid (if applicable)
+        - label: I have searched existing issues for duplicates
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..dd69038
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Questions and Discussions
+    url: https://github.com/CenterForDigitalHumanities/Page-Viewer/discussions
+    about: Ask questions and discuss ideas with the community
+  - name: 📚 IIIF Community
+    url: https://iiif.io/community/
+    about: Join the broader IIIF community for general IIIF questions
+  - name: 🔧 IIIF Technical Questions
+    url: https://groups.google.com/forum/#!forum/iiif-discuss
+    about: Technical questions about IIIF standards and implementation
+  - name: 🏛️ Center for Digital Humanities
+    url: https://digitalhumanities.wustl.edu/
+    about: Learn more about the Center for Digital Humanities at Washington University in St. Louis
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..ddf9ee6
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,131 @@
+name: Feature Request
+description: Suggest a new feature or enhancement for the IIIF Page Viewer
+title: "[Feature]: "
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please provide as much detail as possible to help us understand your request.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve? Is your feature request related to a problem?
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like to see implemented.
+      placeholder: I would like to see...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternative Solutions
+      description: Describe any alternative solutions or features you've considered.
+      placeholder: Another approach could be...
+    validations:
+      required: false
+
+  - type: dropdown
+    id: feature-type
+    attributes:
+      label: Feature Type
+      description: What type of feature is this?
+      options:
+        - IIIF Standard Compliance
+        - User Interface Enhancement
+        - Accessibility Improvement
+        - Performance Optimization
+        - Developer Experience
+        - Documentation
+        - Integration/API
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority Level
+      description: How important is this feature to you?
+      options:
+        - Low - Nice to have
+        - Medium - Would be helpful
+        - High - Important for my use case
+        - Critical - Blocking my project
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Describe your specific use case for this feature.
+      placeholder: |
+        In my digital humanities project, I need to...
+        The current workflow is...
+        This feature would help by...
+    validations:
+      required: true
+
+  - type: textarea
+    id: iiif-context
+    attributes:
+      label: IIIF Context
+      description: How does this relate to IIIF standards or best practices?
+      placeholder: This aligns with IIIF Presentation API v3 by...
+    validations:
+      required: false
+
+  - type: textarea
+    id: implementation-ideas
+    attributes:
+      label: Implementation Ideas
+      description: Do you have any ideas about how this could be implemented?
+      placeholder: |
+        This could be implemented by:
+        1. Adding a new method to...
+        2. Modifying the UI to...
+        3. Supporting additional IIIF properties...
+    validations:
+      required: false
+
+  - type: textarea
+    id: examples
+    attributes:
+      label: Examples or References
+      description: Provide links to similar features in other tools or examples of this functionality.
+      placeholder: |
+        - Similar feature in Tool X: https://example.com
+        - IIIF specification reference: https://iiif.io/api/...
+        - Example manifest that would benefit: https://...
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      description: Are you interested in contributing to this feature?
+      options:
+        - label: I would like to work on implementing this feature
+        - label: I can help with testing this feature
+        - label: I can provide additional IIIF manifests for testing
+        - label: I can help with documentation for this feature
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, or mockups about the feature request here.
+    validations:
+      required: false
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/iiif_compatibility.yml b/.github/ISSUE_TEMPLATE/iiif_compatibility.yml
new file mode 100644
index 0000000..4f67b3b
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/iiif_compatibility.yml
@@ -0,0 +1,144 @@
+name: IIIF Compatibility Issue
+description: Report problems with specific IIIF manifests or IIIF standard compliance
+title: "[IIIF]: "
+labels: ["iiif", "compatibility", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This template is for reporting issues related to IIIF manifest compatibility or IIIF standard compliance.
+
+  - type: textarea
+    id: issue-description
+    attributes:
+      label: IIIF Issue Description
+      description: Describe the IIIF-related problem you're experiencing.
+      placeholder: The viewer fails to load annotations from this IIIF v3 manifest...
+    validations:
+      required: true
+
+  - type: input
+    id: manifest-url
+    attributes:
+      label: IIIF Manifest URL
+      description: Provide the URL of the problematic IIIF manifest.
+      placeholder: https://example.com/iiif/manifest.json
+    validations:
+      required: true
+
+  - type: dropdown
+    id: iiif-version
+    attributes:
+      label: IIIF Version
+      description: Which IIIF Presentation API version is the manifest using?
+      options:
+        - IIIF Presentation API v2
+        - IIIF Presentation API v3
+        - Mixed v2/v3
+        - Unknown
+    validations:
+      required: true
+
+  - type: dropdown
+    id: issue-type
+    attributes:
+      label: Issue Type
+      description: What type of IIIF compatibility issue is this?
+      options:
+        - Manifest parsing error
+        - Canvas loading failure
+        - Annotation display problem
+        - Image service issue
+        - Coordinate mapping problem
+        - Metadata display issue
+        - Navigation structure issue
+        - Other IIIF standard violation
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected IIIF Behavior
+      description: What should happen according to the IIIF specification?
+      placeholder: According to the IIIF Presentation API v3, this manifest should...
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual Behavior
+      description: What actually happens when the viewer processes this manifest?
+      placeholder: Instead, the viewer...
+    validations:
+      required: true
+
+  - type: textarea
+    id: manifest-snippet
+    attributes:
+      label: Relevant Manifest Snippet
+      description: If possible, include the relevant portion of the IIIF manifest JSON.
+      placeholder: |
+        {
+          "@context": "http://iiif.io/api/presentation/3/context.json",
+          "id": "https://example.com/manifest",
+          "type": "Manifest",
+          "items": [...]
+        }
+      render: json
+    validations:
+      required: false
+
+  - type: textarea
+    id: validation-results
+    attributes:
+      label: IIIF Validator Results
+      description: If you've run the manifest through the IIIF validator, please include results.
+      placeholder: |
+        IIIF Validator (https://iiif.io/api/validator/) results:
+        - Error: Missing required property 'id'
+        - Warning: Deprecated property '@id' used instead of 'id'
+    validations:
+      required: false
+
+  - type: input
+    id: institution
+    attributes:
+      label: Institution/Source
+      description: What institution or service provided this IIIF manifest?
+      placeholder: e.g., Harvard Art Museums, Europeana, etc.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: iiif-testing
+    attributes:
+      label: IIIF Testing Checklist
+      description: Testing performed
+      options:
+        - label: I have verified the manifest loads in other IIIF viewers
+        - label: I have checked the manifest with the IIIF validator
+        - label: I have tested with both HTTP and HTTPS versions of the manifest
+        - label: I have confirmed this works with IIIF Presentation API v2 manifests
+        - label: I have confirmed this works with IIIF Presentation API v3 manifests
+
+  - type: textarea
+    id: other-viewers
+    attributes:
+      label: Behavior in Other IIIF Viewers
+      description: How does this manifest behave in other IIIF viewers (Mirador, Universal Viewer, etc.)?
+      placeholder: |
+        - Mirador: Works correctly
+        - Universal Viewer: Same issue
+        - OpenSeadragon: Not applicable
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other relevant information about this IIIF compatibility issue.
+    validations:
+      required: false
\ No newline at end of file
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..eb9171d
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,122 @@
+# Pull Request
+
+## Description
+<!-- Provide a clear and concise description of what this PR accomplishes -->
+
+## Type of Change
+<!-- Please delete options that are not relevant -->
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Code refactoring (no functional changes)
+- [ ] IIIF standard compliance improvement
+
+## Related Issues
+<!-- Link any related issues using "Fixes #issue_number" or "Closes #issue_number" -->
+- Fixes #
+- Related to #
+
+## Changes Made
+<!-- List the specific changes made in this PR -->
+- 
+- 
+- 
+
+## IIIF Testing
+<!-- For IIIF-related changes, describe testing performed -->
+- [ ] Tested with IIIF Presentation API v2 manifests
+- [ ] Tested with IIIF Presentation API v3 manifests
+- [ ] Tested with IIIF Image API integration
+- [ ] Verified coordinate mapping accuracy
+- [ ] Tested annotation display and interaction
+
+### Test Manifests Used
+<!-- List specific IIIF manifests used for testing -->
+- [ ] Example manifest 1: URL here
+- [ ] Example manifest 2: URL here
+- [ ] Institution manifests: List here
+
+## Browser Testing
+<!-- Check all browsers where you've tested this change -->
+- [ ] Chrome (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (latest)
+- [ ] Edge (latest)
+- [ ] Mobile browsers (specify which)
+
+## Accessibility Testing
+<!-- For UI changes, verify accessibility compliance -->
+- [ ] Keyboard navigation works correctly
+- [ ] Screen reader compatibility verified
+- [ ] ARIA labels and roles are appropriate
+- [ ] Color contrast meets WCAG 2.1 AA standards
+- [ ] Focus indicators are visible
+
+## Code Quality Checklist
+- [ ] Code follows the project's style guidelines
+- [ ] Self-review of the code has been performed
+- [ ] Code is commented, particularly in hard-to-understand areas
+- [ ] JSDoc comments added for new public methods
+- [ ] No console.log statements left in production code
+- [ ] Error handling is appropriate and user-friendly
+
+## Testing Checklist
+- [ ] New code has been tested locally
+- [ ] Existing functionality still works
+- [ ] Edge cases have been considered
+- [ ] Performance impact has been assessed
+- [ ] No browser console errors
+
+## Documentation
+- [ ] Documentation has been updated (if needed)
+- [ ] Code comments are clear and helpful
+- [ ] README updated (if applicable)
+- [ ] CHANGELOG updated (if applicable)
+
+## Iframe Integration Testing
+<!-- For changes affecting iframe functionality -->
+- [ ] PostMessage communication works correctly
+- [ ] Parent window integration tested
+- [ ] URL parameter handling works
+- [ ] Cross-origin functionality verified
+
+## Screenshots/Demo
+<!-- Include screenshots or demo GIFs for UI changes -->
+### Before
+<!-- Screenshot or description of behavior before changes -->
+
+### After
+<!-- Screenshot or description of behavior after changes -->
+
+## Performance Impact
+<!-- Describe any performance implications -->
+- [ ] No performance impact
+- [ ] Minor performance improvement
+- [ ] Minor performance regression (justified by functionality)
+- [ ] Significant performance impact (explain)
+
+## Breaking Changes
+<!-- If this is a breaking change, describe the impact and migration path -->
+- [ ] No breaking changes
+- [ ] Breaking changes (describe below)
+
+### Migration Guide
+<!-- For breaking changes, provide migration instructions -->
+
+## Additional Notes
+<!-- Any additional information that reviewers should know -->
+
+## Reviewer Notes
+<!-- Specific areas where you'd like reviewer feedback -->
+- Please pay special attention to:
+- I'm unsure about:
+- Alternative approaches considered:
+
+---
+
+<!-- 
+Thank you for contributing to IIIF Page Viewer! 
+Your contribution helps make IIIF content more accessible to researchers and the public.
+-->
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..786e370
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,113 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build outputs
+dist/
+build/
+out/
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE and editor files
+.vscode/settings.json
+.vscode/launch.json
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+Desktop.ini
+
+# Logs
+logs/
+*.log
+
+# Temporary files
+tmp/
+temp/
+.tmp/
+.temp/
+
+# Coverage reports
+coverage/
+.nyc_output/
+
+# Testing
+.jest/
+junit.xml
+
+# Package managers
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# Backup files
+*.bak
+*.backup
+*.old
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# Documentation build
+docs/_build/
+site/
+
+# Local development
+.local/
+local/
+
+# Screenshots and demos (unless specifically needed)
+screenshots/
+demos/
+*.gif
+*.mp4
+
+# Security
+*.pem
+*.key
+.secrets/
+
+# Editor directories and files
+.vscode/
+!.vscode/extensions.json
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..f598294
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to the IIIF Page Viewer project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive contribution guidelines (CONTRIBUTING.md)
+- AI development guide (COPILOT.md) 
+- Community code of conduct (CODE_OF_CONDUCT.md)
+- Security policy and reporting guidelines (SECURITY.md)
+- GitHub issue templates for bugs, features, and IIIF compatibility
+- Pull request template with comprehensive checklists
+- Development guide (DEVELOPMENT.md)
+- Project metadata in package.json
+- Proper .gitignore file
+
+### Changed
+- Enhanced project documentation structure for open source contribution
+
+## [2.0.0] - 2024-XX-XX
+
+### Added
+- Modular JavaScript architecture with ES6 classes
+- Support for both IIIF Presentation API v2 and v3
+- Automatic IIIF Image API detection and optimization
+- Full accessibility support (WCAG 2.1 AA compliance)
+- Interactive annotation overlays with tooltips
+- Responsive design for various screen sizes
+- Parent window communication via PostMessage API
+- Error handling with user-friendly messages
+- Loading states and visual feedback
+- Keyboard navigation support
+
+### Features
+- **IIIFDataService**: Handles IIIF data fetching and parsing
+- **UIManager**: Manages user interface and rendering
+- **MessageHandler**: Manages parent window communication
+- **PageViewer**: Main orchestrator class
+
+### Browser Support
+- Modern browsers with ES6+ support
+- Fetch API support required
+- PostMessage API for iframe communication
+
+### IIIF Compatibility
+- IIIF Presentation API v2.x and v3.x
+- IIIF Image API v2.x and v3.x (automatic info.json handling)
+- Standard XYWH coordinate selectors
+- Automatic image URL construction from IIIF Image API
+
+## [1.x.x] - Previous Versions
+
+### Note
+Version 1.x.x represents earlier iterations of the project. 
+For detailed history of changes prior to v2.0.0, please refer to the git commit history.
+
+---
+
+## Types of Changes
+
+- `Added` for new features
+- `Changed` for changes in existing functionality
+- `Deprecated` for soon-to-be removed features
+- `Removed` for now removed features
+- `Fixed` for any bug fixes
+- `Security` for vulnerability fixes
+
+## Version Guidelines
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version changes for incompatible API changes
+- **MINOR** version changes for backwards-compatible functionality additions
+- **PATCH** version changes for backwards-compatible bug fixes
+
+## IIIF Standard Updates
+
+When IIIF specifications are updated, we will:
+
+- Assess compatibility impact
+- Update implementation as needed
+- Maintain backward compatibility when possible
+- Document any breaking changes clearly
+
+## Contributing to the Changelog
+
+- All notable changes should be documented here
+- Keep entries brief but descriptive
+- Link to relevant issues/PRs when applicable
+- Group changes by type (Added, Changed, Fixed, etc.)
+- Follow the established format and style
\ No newline at end of file
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..9d655d8
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,93 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in the IIIF Page Viewer project and our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+- Supporting the open source mission and IIIF community standards
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Academic and Digital Humanities Context
+
+As a project from the Center for Digital Humanities, we additionally emphasize:
+
+- **Scholarly Integrity**: Respect for intellectual property, proper attribution, and honest collaboration
+- **Digital Accessibility**: Commitment to making digital tools accessible to all users, including those with disabilities
+- **Open Scholarship**: Supporting open access principles and transparent research practices
+- **Cultural Sensitivity**: Recognizing that IIIF content often includes cultural heritage materials that require respectful handling
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at the Center for Digital Humanities. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..c8a562f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,197 @@
+# Contributing to IIIF Page Viewer
+
+Thank you for your interest in contributing to the IIIF Page Viewer! This project is maintained by the Center for Digital Humanities and welcomes contributions from the community.
+
+## Getting Started
+
+### Prerequisites
+
+- A modern web browser with ES6+ support
+- Basic knowledge of HTML, CSS, and JavaScript
+- Understanding of IIIF (International Image Interoperability Framework) is helpful but not required
+
+### Local Development Setup
+
+1. **Fork and Clone the Repository**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/Page-Viewer.git
+   cd Page-Viewer
+   ```
+
+2. **Start a Local Development Server**
+   ```bash
+   # Using Python 3
+   python3 -m http.server 8000
+   
+   # Using Node.js (if you have it installed)
+   npx serve .
+   
+   # Using PHP
+   php -S localhost:8000
+   ```
+
+3. **Open in Browser**
+   Navigate to `http://localhost:8000` to view the application.
+
+4. **Test with IIIF Content**
+   You can test the viewer by adding a canvas parameter:
+   ```
+   http://localhost:8000?canvas=https://example.com/iiif/manifest.json
+   ```
+
+## Project Structure
+
+```
+Page-Viewer/
+├── index.html              # Main HTML file
+├── viewer.js              # Main orchestrator class
+├── iiif-data-service.js   # IIIF data fetching and parsing
+├── ui-manager.js          # UI operations and rendering
+├── message-handler.js     # Parent window communication
+├── styles.css             # Styling
+└── README.md              # Project documentation
+```
+
+## How to Contribute
+
+### Reporting Issues
+
+- Use the GitHub issue tracker to report bugs or request features
+- Check existing issues before creating a new one
+- Provide detailed information including:
+  - Browser and version
+  - Steps to reproduce the issue
+  - Expected vs. actual behavior
+  - IIIF manifest URLs (if relevant)
+
+### Making Changes
+
+1. **Create a Feature Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make Your Changes**
+   - Follow the existing code style and patterns
+   - Write clear, descriptive commit messages
+   - Test your changes across different browsers
+
+3. **Test Thoroughly**
+   - Test with various IIIF manifests (v2 and v3)
+   - Verify accessibility features work
+   - Check responsive design on different screen sizes
+   - Test iframe communication functionality
+
+4. **Commit Your Changes**
+   ```bash
+   git add .
+   git commit -m "Add descriptive commit message"
+   ```
+
+5. **Push and Create Pull Request**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+## Code Standards
+
+### JavaScript Style Guide
+
+- Use ES6+ modules and modern JavaScript features
+- Use consistent indentation (2 spaces)
+- Include JSDoc comments for public methods
+- Use descriptive variable and function names
+- Handle errors gracefully with user-friendly messages
+
+### CSS Guidelines
+
+- Use semantic class names
+- Follow mobile-first responsive design
+- Maintain accessibility standards (WCAG 2.1 AA)
+- Use CSS custom properties for theming when appropriate
+
+### HTML Standards
+
+- Use semantic HTML5 elements
+- Include proper ARIA labels and roles
+- Ensure keyboard navigation works
+- Test with screen readers
+
+## Testing Guidelines
+
+### Manual Testing Checklist
+
+- [ ] Loads IIIF v2 and v3 manifests correctly
+- [ ] Displays images and annotations properly
+- [ ] Responsive design works on mobile and desktop
+- [ ] Keyboard navigation functions correctly
+- [ ] Screen reader compatibility
+- [ ] Error handling displays appropriate messages
+- [ ] iframe communication works with parent windows
+
+### Browser Compatibility
+
+Test your changes in:
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Types of Contributions Welcome
+
+### Bug Fixes
+- Fix rendering issues
+- Improve error handling
+- Resolve browser compatibility problems
+
+### Features
+- IIIF standard compliance improvements
+- Accessibility enhancements
+- Performance optimizations
+- New annotation features
+
+### Documentation
+- Code comments and JSDoc
+- Usage examples
+- API documentation
+- Tutorial content
+
+### Design Improvements
+- UI/UX enhancements
+- Responsive design improvements
+- Accessibility improvements
+
+## IIIF-Specific Considerations
+
+### IIIF Standards Support
+- Ensure compatibility with both IIIF Presentation API v2 and v3
+- Support IIIF Image API v2 and v3
+- Follow IIIF best practices for coordinate parsing (XYWH format)
+
+### Testing with Real IIIF Content
+Test your changes with manifests from:
+- Digital libraries and museums
+- IIIF community examples
+- Various IIIF service providers
+
+## Communication
+
+- **GitHub Issues**: For bug reports and feature requests
+- **Pull Requests**: For code contributions
+- **Discussions**: For questions and general discussion
+
+## Recognition
+
+Contributors will be acknowledged in:
+- Git commit history
+- README.md contributors section (if we add one)
+- Release notes for significant contributions
+
+## Questions?
+
+If you have questions about contributing, please:
+1. Check the existing documentation
+2. Search closed issues for similar questions
+3. Open a new issue with the "question" label
+
+We appreciate your interest in making IIIF Page Viewer better for everyone!
\ No newline at end of file
diff --git a/COPILOT.md b/COPILOT.md
new file mode 100644
index 0000000..0cdb53d
--- /dev/null
+++ b/COPILOT.md
@@ -0,0 +1,237 @@
+# AI Development Guide for IIIF Page Viewer
+
+This guide provides specific instructions for AI assistants (like GitHub Copilot, ChatGPT, Claude, etc.) working on the IIIF Page Viewer project.
+
+## Project Overview
+
+**Type**: JavaScript-based IIIF (International Image Interoperability Framework) viewer  
+**Architecture**: Modular ES6 classes with no build dependencies  
+**Primary Use**: Embedded iframe component for displaying IIIF images and annotations  
+**Standards**: IIIF Presentation API v2/v3, IIIF Image API v2/v3  
+
+## Quick Setup for AI Development
+
+```bash
+# Clone and serve locally
+git clone https://github.com/CenterForDigitalHumanities/Page-Viewer.git
+cd Page-Viewer
+python3 -m http.server 8000
+# Test at: http://localhost:8000?canvas=[IIIF_MANIFEST_URL]
+```
+
+## Architecture Pattern
+
+The codebase follows a **modular class-based architecture**:
+
+```javascript
+PageViewer (orchestrator)
+├── IIIFDataService (data fetching/parsing)
+├── UIManager (rendering/user interaction)
+└── MessageHandler (iframe communication)
+```
+
+### Key Design Principles
+- **No build tools**: Pure ES6 modules, no transpilation
+- **Iframe-first**: Designed for embedding in other applications
+- **IIIF compliance**: Strict adherence to IIIF standards
+- **Accessibility**: WCAG 2.1 AA compliance required
+- **Error resilience**: Graceful degradation for failed requests
+
+## Development Guidelines for AI
+
+### Code Style Requirements
+
+```javascript
+// ✅ Preferred patterns
+class ExampleClass {
+    /**
+     * JSDoc for all public methods
+     * @param {string} param - Description
+     * @returns {Promise<Object>} Description
+     */
+    async methodName(param) {
+        try {
+            // Handle errors gracefully
+            const result = await this.someOperation(param)
+            return result
+        } catch (error) {
+            console.error("Context-specific error message:", error)
+            throw new Error("User-friendly error message")
+        }
+    }
+}
+
+// ✅ Error handling pattern
+this.uiManager.showError("Failed to load canvas: " + error.message)
+
+// ✅ Accessibility requirements
+element.setAttribute('aria-label', 'Descriptive label')
+element.setAttribute('role', 'appropriate-role')
+```
+
+### IIIF-Specific Implementation Notes
+
+#### IIIF Manifest Parsing
+```javascript
+// Handle both v2 and v3 formats
+const canvases = manifest['@type'] === 'sc:Manifest' 
+    ? manifest.sequences?.[0]?.canvases || []  // v2
+    : manifest.items || []                     // v3
+
+// Coordinate parsing (XYWH format)
+const coords = selector.value || selector['@value'] || selector
+// Expected format: "xywh=x,y,w,h" or "x,y,w,h"
+```
+
+#### Image API Integration
+```javascript
+// Auto-detect IIIF Image API info.json
+if (response.headers.get('content-type')?.includes('application/json')) {
+    const info = await response.json()
+    if (info['@context']?.includes('iiif.io')) {
+        // Construct optimized image URL
+        return `${baseUrl}/full/${width},${height}/0/default.jpg`
+    }
+}
+```
+
+### Testing Requirements
+
+**Essential test scenarios for AI to verify**:
+```bash
+# Test with real IIIF content
+http://localhost:8000?canvas=https://iiif.library.nulib.northwestern.edu/iiif/2/180682d0-4d51-0132-412f-0050569601ca-8/manifest.json
+
+# Test iframe communication
+parent.postMessage({type: "CANVAS_URL", canvasUrl: "..."}, "*")
+
+# Test error handling
+http://localhost:8000?canvas=https://invalid-url.com/manifest.json
+```
+
+### Common Patterns for AI to Follow
+
+#### 1. Adding New Features
+```javascript
+// 1. Extend appropriate class
+class UIManager {
+    async newFeature(params) {
+        // 2. Add loading state
+        this.showLoading("Loading new feature...")
+        
+        try {
+            // 3. Implement feature
+            const result = await this.processFeature(params)
+            
+            // 4. Update UI
+            this.updateDisplay(result)
+            
+        } catch (error) {
+            // 5. Handle errors gracefully
+            console.error("Feature error:", error)
+            this.showError("Feature failed: " + error.message)
+        }
+    }
+}
+```
+
+#### 2. IIIF Data Processing
+```javascript
+// Always handle both v2/v3 formats
+function extractCanvasData(canvas) {
+    const id = canvas['@id'] || canvas.id
+    const images = canvas.images || canvas.items || []
+    const annotations = canvas.otherContent || canvas.annotations || []
+    
+    // Extract with fallbacks
+    return { id, images, annotations }
+}
+```
+
+#### 3. UI Updates
+```javascript
+// Follow accessibility patterns
+function createAnnotationElement(annotation) {
+    const element = document.createElement('div')
+    element.className = 'annotation-overlay'
+    element.setAttribute('role', 'button')
+    element.setAttribute('tabindex', '0')
+    element.setAttribute('aria-label', `Annotation: ${annotation.label}`)
+    
+    // Add keyboard support
+    element.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            this.handleAnnotationClick(annotation)
+        }
+    })
+    
+    return element
+}
+```
+
+## Debugging Tips for AI
+
+### Console Debugging
+```javascript
+// Enable verbose logging
+console.log("IIIF Data:", { manifest, canvas, annotations })
+console.log("Image dimensions:", { width, height, aspectRatio })
+console.log("Coordinate mapping:", { original, scaled, percentage })
+```
+
+### Common Issues and Solutions
+
+| Issue | Likely Cause | Solution |
+|-------|--------------|----------|
+| Images not loading | CORS or invalid URL | Check network tab, verify IIIF Image API |
+| Annotations misaligned | Coordinate calculation error | Verify XYWH parsing and aspect ratio |
+| Parent communication fails | PostMessage syntax | Check message format and origin |
+| Accessibility violations | Missing ARIA attributes | Add role, aria-label, tabindex |
+
+## File Modification Guidelines
+
+### High-change files (modify freely)
+- `ui-manager.js` - UI features and styling
+- `styles.css` - Visual improvements
+- Documentation files
+
+### Medium-change files (modify carefully)
+- `iiif-data-service.js` - IIIF parsing logic
+- `viewer.js` - Main orchestration
+- `index.html` - Structure changes
+
+### Low-change files (minimal changes only)
+- `message-handler.js` - Core communication logic
+
+## Quality Checklist for AI
+
+Before submitting changes, verify:
+
+- [ ] Code follows ES6 module patterns
+- [ ] All public methods have JSDoc comments
+- [ ] Error handling includes user-friendly messages
+- [ ] IIIF v2 and v3 compatibility maintained
+- [ ] Accessibility attributes present (aria-label, role, tabindex)
+- [ ] Manual testing with real IIIF manifest
+- [ ] Browser console shows no errors
+- [ ] Responsive design works on mobile/desktop
+- [ ] iframe communication tested if relevant
+
+## Resources for AI Context
+
+**IIIF Standards References**:
+- [IIIF Presentation API](https://iiif.io/api/presentation/)
+- [IIIF Image API](https://iiif.io/api/image/)
+
+**Example IIIF Manifests for Testing**:
+- Northwestern University: `https://iiif.library.nulib.northwestern.edu/iiif/2/[id]/manifest.json`
+- Digital Public Library of America: Various manifests available
+- Harvard Art Museums: IIIF-compliant collections
+
+**Key Dependencies to Understand**:
+- ES6 Modules (import/export)
+- Fetch API for HTTP requests
+- PostMessage API for iframe communication
+- Canvas/Image manipulation for coordinate mapping
+
+This guide should provide sufficient context for AI assistants to contribute effectively while maintaining code quality and IIIF compliance standards.
\ No newline at end of file
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..5af1bab
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,370 @@
+# Development Guide
+
+This guide provides detailed instructions for setting up a development environment and contributing to the IIIF Page Viewer project.
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/CenterForDigitalHumanities/Page-Viewer.git
+cd Page-Viewer
+
+# Start development server
+python3 -m http.server 8000
+
+# Open in browser
+# http://localhost:8000?canvas=https://example.com/iiif/manifest.json
+```
+
+## Development Environment Setup
+
+### Prerequisites
+
+#### Required
+- **Modern Web Browser**: Chrome 88+, Firefox 78+, Safari 14+, or Edge 88+
+- **HTTP Server**: Any local server (Python, Node.js, PHP, etc.)
+- **Git**: For version control
+- **Text Editor/IDE**: VS Code, WebStorm, or similar with JavaScript support
+
+#### Recommended
+- **Browser Developer Tools**: Familiar with debugging JavaScript
+- **IIIF Knowledge**: Basic understanding of IIIF standards (helpful but not required)
+
+### Local Server Options
+
+#### Python (Recommended)
+```bash
+# Python 3
+python3 -m http.server 8000
+
+# Python 2 (if needed)
+python -m SimpleHTTPServer 8000
+```
+
+#### Node.js
+```bash
+# Install serve globally
+npm install -g serve
+
+# Serve current directory
+serve -p 8000
+```
+
+#### PHP
+```bash
+php -S localhost:8000
+```
+
+#### Live Server (VS Code Extension)
+1. Install "Live Server" extension in VS Code
+2. Right-click on `index.html`
+3. Select "Open with Live Server"
+
+## Project Architecture
+
+### File Structure
+```
+Page-Viewer/
+├── index.html              # Main HTML entry point
+├── viewer.js              # Main orchestrator class
+├── iiif-data-service.js   # IIIF data handling
+├── ui-manager.js          # UI rendering and interactions
+├── message-handler.js     # Parent window communication
+├── styles.css             # All styling
+├── README.md              # Project overview
+├── CONTRIBUTING.md        # Contribution guidelines
+├── COPILOT.md            # AI development guide
+├── DEVELOPMENT.md         # This file
+└── .github/               # GitHub templates and workflows
+```
+
+### Module Dependencies
+```
+PageViewer (main orchestrator)
+├── IIIFDataService (data layer)
+├── UIManager (presentation layer)
+└── MessageHandler (communication layer)
+```
+
+## Development Workflow
+
+### 1. Setting Up Your Branch
+
+```bash
+# Create feature branch
+git checkout -b feature/your-feature-name
+
+# Or bug fix branch
+git checkout -b fix/issue-description
+```
+
+### 2. Development Process
+
+#### File Watching Setup
+For automatic reload during development:
+
+```bash
+# Using nodemon (if you have Node.js)
+npm install -g nodemon
+nodemon --exec "echo 'Files changed, refresh browser'" --watch . --ext js,html,css
+
+# Manual approach: refresh browser after changes
+```
+
+#### Testing Changes
+1. **Manual Testing**: Test functionality in browser
+2. **Cross-Browser Testing**: Test in different browsers
+3. **IIIF Testing**: Test with various IIIF manifests
+4. **Accessibility Testing**: Use screen reader, keyboard navigation
+
+### 3. Code Quality
+
+#### JavaScript Standards
+- Use ES6+ features (classes, modules, async/await)
+- Follow consistent indentation (2 spaces)
+- Use descriptive variable and function names
+- Include JSDoc comments for public methods
+- Handle errors gracefully
+
+#### Example Code Structure
+```javascript
+/**
+ * Example class following project patterns
+ */
+class ExampleClass {
+    constructor(options = {}) {
+        this.option = options.option || 'default'
+    }
+
+    /**
+     * Example method with JSDoc
+     * @param {string} param - Description of parameter
+     * @returns {Promise<Object>} Description of return value
+     */
+    async exampleMethod(param) {
+        try {
+            // Implementation here
+            const result = await this.processData(param)
+            return result
+        } catch (error) {
+            console.error('Example method error:', error)
+            throw new Error(`Failed to process: ${error.message}`)
+        }
+    }
+}
+```
+
+## Testing
+
+### Manual Testing Checklist
+
+#### Basic Functionality
+- [ ] Page loads without errors
+- [ ] IIIF manifest loads correctly
+- [ ] Images display properly
+- [ ] Annotations render correctly
+- [ ] Error messages display appropriately
+
+#### IIIF Compatibility
+- [ ] IIIF Presentation API v2 manifests work
+- [ ] IIIF Presentation API v3 manifests work
+- [ ] IIIF Image API integration functions
+- [ ] Various manifest structures supported
+- [ ] Canvas selection works (fragment identifiers)
+
+#### Browser Compatibility
+- [ ] Chrome (latest)
+- [ ] Firefox (latest) 
+- [ ] Safari (latest)
+- [ ] Edge (latest)
+- [ ] Mobile browsers
+
+#### Accessibility
+- [ ] Keyboard navigation works
+- [ ] Screen reader announces content properly
+- [ ] Focus indicators are visible
+- [ ] ARIA labels are appropriate
+- [ ] Color contrast meets standards
+
+#### iframe Integration
+- [ ] Loads correctly in iframe
+- [ ] PostMessage communication works
+- [ ] URL parameters handled properly
+- [ ] Parent window receives events
+
+### Test IIIF Manifests
+
+#### Basic Testing
+```
+# Simple IIIF v3 manifest
+https://iiif.io/api/presentation/3.0/example/fixtures/001/manifest.json
+
+# IIIF v2 manifest with annotations
+https://iiif.library.nulib.northwestern.edu/iiif/2/180682d0-4d51-0132-412f-0050569601ca-8/manifest.json
+```
+
+#### Advanced Testing
+Test with manifests from various institutions:
+- Harvard Art Museums
+- Digital Public Library of America
+- Europeana
+- Bodleian Libraries
+- Stanford Libraries
+
+### Performance Testing
+
+#### Network Conditions
+- Test with slow connections
+- Test with failed network requests
+- Test with large image files
+- Test with many annotations
+
+#### Browser Performance
+- Check memory usage
+- Monitor for memory leaks
+- Test with DevTools throttling
+
+## Debugging
+
+### Browser Developer Tools
+
+#### Console Debugging
+```javascript
+// Add temporary debugging
+console.log('IIIF Data:', manifest)
+console.log('Canvas dimensions:', { width, height })
+console.log('Annotation coordinates:', coordinates)
+```
+
+#### Network Debugging
+- Monitor Network tab for failed requests
+- Check CORS issues
+- Verify IIIF manifest structure
+- Test Image API responses
+
+#### Common Issues and Solutions
+
+| Issue | Symptoms | Solution |
+|-------|----------|-----------|
+| CORS errors | Network failures, console errors | Check IIIF service CORS headers |
+| Images not loading | Broken image icons | Verify image URLs and IIIF Image API |
+| Annotations misaligned | Overlays in wrong positions | Check coordinate parsing and scaling |
+| iframe communication fails | No parent window messages | Verify PostMessage syntax and origins |
+
+### Debugging Workflow
+1. **Reproduce the issue** in development environment
+2. **Check browser console** for errors
+3. **Inspect network requests** for failures
+4. **Test with known-good IIIF manifests**
+5. **Isolate the problem** to specific component
+6. **Create minimal test case**
+7. **Fix and verify** solution
+
+## Code Style and Standards
+
+### ESLint Configuration (Optional)
+If you want to add linting:
+
+```json
+{
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "extends": ["eslint:recommended"],
+  "parserOptions": {
+    "ecmaVersion": 12,
+    "sourceType": "module"
+  },
+  "rules": {
+    "indent": ["error", 2],
+    "quotes": ["error", "single"],
+    "semi": ["error", "never"]
+  }
+}
+```
+
+### CSS Standards
+- Use semantic class names
+- Follow BEM methodology where appropriate
+- Mobile-first responsive design
+- Accessibility-compliant colors and contrast
+
+### HTML Standards
+- Use semantic HTML5 elements
+- Include proper ARIA attributes
+- Ensure keyboard accessibility
+- Validate markup when possible
+
+## Deployment
+
+### Production Considerations
+- Minify JavaScript and CSS for production
+- Test with production IIIF services
+- Verify HTTPS compatibility
+- Test iframe embedding scenarios
+
+### Static Site Deployment
+This project can be deployed to any static hosting service:
+- GitHub Pages
+- Netlify
+- Vercel
+- AWS S3
+- Any web server
+
+## Advanced Development
+
+### Adding New Features
+
+#### 1. Plan the Feature
+- Review IIIF specifications
+- Design the API/interface
+- Consider backward compatibility
+- Plan testing approach
+
+#### 2. Implement
+- Follow existing patterns
+- Add appropriate error handling
+- Include JSDoc documentation
+- Test thoroughly
+
+#### 3. Integration
+- Update main classes as needed
+- Ensure proper module imports
+- Test iframe communication impact
+- Verify accessibility
+
+### Extending IIIF Support
+
+#### Adding New IIIF Properties
+1. Update `IIIFDataService` parsing
+2. Modify `UIManager` rendering
+3. Test with real manifests
+4. Update documentation
+
+#### Performance Optimization
+- Profile JavaScript execution
+- Optimize image loading
+- Cache IIIF data appropriately
+- Minimize DOM manipulations
+
+## Getting Help
+
+### Resources
+- **IIIF Documentation**: https://iiif.io/api/
+- **MDN Web Docs**: https://developer.mozilla.org/
+- **Accessibility Guidelines**: https://www.w3.org/WAI/WCAG21/quickref/
+
+### Community
+- Open GitHub issues for questions
+- Check existing documentation
+- Join IIIF community discussions
+
+### Code Review Process
+1. Create pull request with detailed description
+2. Wait for maintainer review
+3. Address feedback promptly
+4. Test changes after feedback
+5. Merge when approved
+
+This development guide should provide everything you need to contribute effectively to the IIIF Page Viewer project!
\ No newline at end of file
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..a57b065
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Center for Digital Humanities, Washington University in St. Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
\ No newline at end of file
diff --git a/README.md b/README.md
index 14c79b0..378735c 100644
--- a/README.md
+++ b/README.md
@@ -134,7 +134,27 @@ Example flow:
 - Supports standard XYWH coordinate selectors
 - Automatic image URL construction from IIIF Image API info.json responses
 
-## Development
+## Contributing
+
+We welcome contributions from the community! This project is maintained by the [Center for Digital Humanities](https://digitalhumanities.wustl.edu/) at Washington University in St. Louis.
+
+### Quick Start for Contributors
+
+1. **Fork and clone** the repository
+2. **Set up development environment**: See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed instructions
+3. **Read the contribution guidelines**: [CONTRIBUTING.md](CONTRIBUTING.md)
+4. **Check out the AI development guide**: [COPILOT.md](COPILOT.md) for AI assistants
+
+### Ways to Contribute
+
+- 🐛 **Report bugs** using our [issue templates](.github/ISSUE_TEMPLATE/)
+- 💡 **Suggest features** for IIIF functionality improvements
+- 📝 **Improve documentation** and examples
+- 🔧 **Submit code** for bug fixes and new features
+- 🧪 **Test with IIIF manifests** from various institutions
+- ♿ **Enhance accessibility** features
+
+### Development
 
 The modular architecture makes it easy to:
 
@@ -142,3 +162,22 @@ The modular architecture makes it easy to:
 - **Modify styling**: Edit `styles.css` for visual changes
 - **Add message types**: Extend `MessageHandler` for new communication patterns
 - **Customize UI**: Modify `UIManager` for different interaction patterns
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development instructions.
+
+## Community and Support
+
+- 📋 **Issues**: Report bugs and request features via [GitHub Issues](https://github.com/CenterForDigitalHumanities/Page-Viewer/issues)
+- 💬 **Discussions**: Join conversations in [GitHub Discussions](https://github.com/CenterForDigitalHumanities/Page-Viewer/discussions)
+- 🏛️ **Institution**: [Center for Digital Humanities](https://digitalhumanities.wustl.edu/)
+- 🌐 **IIIF Community**: Connect with the broader [IIIF community](https://iiif.io/community/)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- **IIIF Community**: For developing and maintaining the IIIF standards
+- **Contributors**: All developers who have contributed to this project
+- **Digital Humanities Community**: For supporting open source tools for cultural heritage
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..fca5a04
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,178 @@
+# Security Policy
+
+## Supported Versions
+
+We actively support the following versions of IIIF Page Viewer with security updates:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.0.x   | :white_check_mark: |
+| 1.x.x   | :x:                |
+
+## Security Considerations
+
+### IIIF Content Security
+
+The IIIF Page Viewer loads and displays external content from IIIF manifests and image services. Users should be aware of the following security considerations:
+
+#### Content Source Validation
+- **HTTPS Recommended**: Always use HTTPS URLs for IIIF manifests and images when possible
+- **Trusted Sources**: Only load IIIF content from trusted cultural institutions and digital libraries
+- **Content Validation**: The viewer performs basic validation of IIIF manifest structure but cannot guarantee the safety of all external content
+
+#### Cross-Origin Resource Sharing (CORS)
+- The viewer makes cross-origin requests to IIIF services
+- Ensure your IIIF services properly configure CORS headers
+- Be aware that loading IIIF content may expose your users' IP addresses to external services
+
+#### iframe Embedding Security
+- The viewer is designed to run in iframe contexts
+- Parent pages should implement appropriate Content Security Policy (CSP) headers
+- Use appropriate iframe sandboxing attributes when embedding:
+  ```html
+  <iframe src="page-viewer.html" 
+          sandbox="allow-scripts allow-same-origin allow-forms"
+          csp="default-src 'self' https:"></iframe>
+  ```
+
+### Data Privacy
+
+#### Information Collected
+- The viewer does not collect or store personal information
+- No analytics or tracking are implemented by default
+- Image requests to IIIF services may be logged by those services
+
+#### PostMessage Communication
+- The viewer uses `postMessage` API for iframe communication
+- Messages are not encrypted and may be visible to parent pages
+- Avoid sending sensitive information through these communications
+
+## Reporting a Vulnerability
+
+We take security vulnerabilities seriously. If you discover a security vulnerability in IIIF Page Viewer, please follow these steps:
+
+### How to Report
+
+1. **Do not create a public GitHub issue** for security vulnerabilities
+2. **Email**: Send details to the Center for Digital Humanities security team
+3. **Include**: 
+   - Description of the vulnerability
+   - Steps to reproduce the issue
+   - Affected versions
+   - Potential impact assessment
+   - Suggested fix (if available)
+
+### What to Expect
+
+- **Initial Response**: Within 48 hours of receiving your report
+- **Assessment**: We will assess the vulnerability within 5 business days
+- **Updates**: Regular updates on our progress every 5 business days
+- **Resolution**: Security fixes will be prioritized and released as soon as possible
+
+### Disclosure Policy
+
+- **Coordinated Disclosure**: We follow a coordinated disclosure process
+- **Public Disclosure**: Vulnerabilities will be publicly disclosed after a fix is available
+- **Timeline**: We aim to resolve critical vulnerabilities within 30 days
+- **Recognition**: Security researchers will be credited (with permission) in our acknowledgments
+
+## Security Best Practices for Users
+
+### For Developers Integrating the Viewer
+
+```html
+<!-- Recommended iframe configuration -->
+<iframe src="iiif-page-viewer.html"
+        sandbox="allow-scripts allow-same-origin"
+        referrerpolicy="no-referrer-when-downgrade"
+        loading="lazy">
+</iframe>
+```
+
+```javascript
+// Validate IIIF URLs before loading
+function isValidIIIFUrl(url) {
+    try {
+        const parsed = new URL(url)
+        return parsed.protocol === 'https:' && 
+               parsed.hostname.length > 0
+    } catch {
+        return false
+    }
+}
+
+// Safe message handling
+window.addEventListener('message', (event) => {
+    // Always validate origin
+    if (event.origin !== 'https://trusted-domain.com') {
+        return
+    }
+    
+    // Validate message structure
+    if (event.data?.type === 'CANVAS_URL' && 
+        isValidIIIFUrl(event.data.canvasUrl)) {
+        // Process message
+    }
+})
+```
+
+### Content Security Policy (CSP) Recommendations
+
+```http
+Content-Security-Policy: 
+    default-src 'self';
+    img-src 'self' https: data:;
+    script-src 'self' 'unsafe-inline';
+    style-src 'self' 'unsafe-inline';
+    connect-src 'self' https:;
+    frame-ancestors 'self' https://trusted-parent-domain.com;
+```
+
+### For IIIF Service Providers
+
+- **CORS Configuration**: Properly configure CORS headers for cross-origin access
+- **HTTPS**: Serve IIIF manifests and images over HTTPS
+- **Rate Limiting**: Implement appropriate rate limiting to prevent abuse
+- **Access Logs**: Monitor access logs for unusual patterns
+
+## Known Security Limitations
+
+### Client-Side Only
+- All processing happens in the browser
+- Cannot perform server-side validation of IIIF content
+- Relies on browser security features
+
+### External Dependencies
+- The viewer loads external IIIF content that we cannot control
+- Users should verify the trustworthiness of IIIF service providers
+- No malware scanning of loaded images
+
+### Browser Compatibility
+- Security features depend on modern browser capabilities
+- Older browsers may have additional vulnerabilities
+- Users should keep browsers updated
+
+## Security-Related Configuration
+
+### Environment Variables / Configuration
+This project does not use server-side configuration or environment variables that could expose sensitive information.
+
+### Logging
+- The viewer logs errors to browser console for debugging
+- No sensitive information should be logged
+- Production deployments should minimize console output
+
+## Acknowledgments
+
+We would like to thank the security researchers and community members who help make IIIF Page Viewer more secure through responsible disclosure.
+
+## Additional Resources
+
+- [OWASP JavaScript Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html)
+- [IIIF Security Considerations](https://iiif.io/api/annex/notes/security/)
+- [Content Security Policy Guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+- [iframe Security Best Practices](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#security)
+
+---
+
+*This security policy is reviewed and updated regularly. Last updated: [Current Date]*
\ No newline at end of file
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..3fc3ff7
--- /dev/null
+++ b/package.json
@@ -0,0 +1,80 @@
+{
+  "name": "iiif-page-viewer",
+  "version": "2.0.0",
+  "description": "A lightweight IIIF (International Image Interoperability Framework) image viewing tool designed for inclusion as an iframe element in other documents",
+  "main": "viewer.js",
+  "type": "module",
+  "scripts": {
+    "start": "python3 -m http.server 8000",
+    "serve": "python3 -m http.server 8000",
+    "dev": "python3 -m http.server 8000"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CenterForDigitalHumanities/Page-Viewer.git"
+  },
+  "keywords": [
+    "iiif",
+    "image-viewer",
+    "digital-humanities",
+    "iframe",
+    "annotations",
+    "presentation-api",
+    "image-api",
+    "cultural-heritage",
+    "web-components",
+    "accessibility"
+  ],
+  "author": {
+    "name": "Center for Digital Humanities",
+    "url": "https://digitalhumanities.wustl.edu/"
+  },
+  "contributors": [
+    {
+      "name": "Priyal Patel",
+      "email": "mepripri@users.noreply.github.com",
+      "url": "https://github.com/mepripri"
+    },
+    {
+      "name": "Patrick Cuba",
+      "email": "cubap@users.noreply.github.com", 
+      "url": "https://github.com/cubap"
+    }
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/CenterForDigitalHumanities/Page-Viewer/issues"
+  },
+  "homepage": "https://github.com/CenterForDigitalHumanities/Page-Viewer#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "browserslist": [
+    "last 2 Chrome versions",
+    "last 2 Firefox versions",
+    "last 2 Safari versions",
+    "last 2 Edge versions"
+  ],
+  "funding": {
+    "type": "institutional",
+    "url": "https://digitalhumanities.wustl.edu/"
+  },
+  "directories": {
+    "doc": "docs"
+  },
+  "files": [
+    "index.html",
+    "viewer.js",
+    "iiif-data-service.js",
+    "ui-manager.js",
+    "message-handler.js",
+    "styles.css",
+    "README.md",
+    "CONTRIBUTING.md",
+    "COPILOT.md",
+    "DEVELOPMENT.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ]
+}
\ No newline at end of file

From 994f9b19e5898d8aff3c950d41d75ea09eb7422d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 24 Sep 2025 22:44:41 +0000
Subject: [PATCH 4/4] Add GitHub Actions workflows for CI/CD and deployment

Co-authored-by: cubap <1119165+cubap@users.noreply.github.com>
---
 .github/workflows/ci.yml     | 203 +++++++++++++++++++++++++++++++++++
 .github/workflows/deploy.yml | 187 ++++++++++++++++++++++++++++++++
 2 files changed, 390 insertions(+)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .github/workflows/deploy.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..0ac30ce
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,203 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '18'
+        
+    - name: Install dependencies (if package.json has deps)
+      run: |
+        if [ -f package.json ] && grep -q '"dependencies"' package.json; then
+          npm ci
+        else
+          echo "No dependencies to install"
+        fi
+        
+    - name: Start HTTP server
+      run: |
+        python3 -m http.server 8000 &
+        SERVER_PID=$!
+        echo "SERVER_PID=$SERVER_PID" >> $GITHUB_ENV
+        sleep 2
+        
+    - name: Test server response
+      run: |
+        curl -f http://localhost:8000/index.html || exit 1
+        echo "✅ Server is responding"
+        
+    - name: Validate HTML
+      run: |
+        # Check if HTML files are valid
+        for file in *.html; do
+          if [ -f "$file" ]; then
+            echo "Checking $file..."
+            # Basic validation - check for DOCTYPE and closing tags
+            if ! grep -q "<!DOCTYPE" "$file"; then
+              echo "❌ Missing DOCTYPE in $file"
+              exit 1
+            fi
+            if ! grep -q "</html>" "$file"; then
+              echo "❌ Missing closing </html> tag in $file"
+              exit 1
+            fi
+            echo "✅ $file appears valid"
+          fi
+        done
+        
+    - name: Validate JavaScript modules
+      run: |
+        # Check JavaScript files for basic syntax issues
+        for file in *.js; do
+          if [ -f "$file" ]; then
+            echo "Checking $file..."
+            # Use Node.js to check syntax
+            node -c "$file" || exit 1
+            echo "✅ $file syntax is valid"
+          fi
+        done
+        
+    - name: Check for required files
+      run: |
+        echo "Checking for required project files..."
+        required_files=(
+          "index.html"
+          "viewer.js"
+          "iiif-data-service.js"
+          "ui-manager.js"
+          "message-handler.js"
+          "styles.css"
+          "README.md"
+          "CONTRIBUTING.md"
+          "COPILOT.md"
+          "LICENSE"
+        )
+        
+        for file in "${required_files[@]}"; do
+          if [ ! -f "$file" ]; then
+            echo "❌ Missing required file: $file"
+            exit 1
+          else
+            echo "✅ Found: $file"
+          fi
+        done
+        
+    - name: Test IIIF viewer functionality
+      run: |
+        # Test that the viewer loads with URL parameters
+        response=$(curl -s -w "%{http_code}" http://localhost:8000/?canvas=test)
+        if [[ ${response: -3} == "200" ]]; then
+          echo "✅ Viewer responds to URL parameters"
+        else
+          echo "❌ Viewer failed to respond properly"
+          exit 1
+        fi
+        
+    - name: Cleanup
+      if: always()
+      run: |
+        if [ ! -z "$SERVER_PID" ]; then
+          kill $SERVER_PID || true
+        fi
+
+  lint-documentation:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      
+    - name: Check Markdown files
+      run: |
+        echo "Checking Markdown files for basic issues..."
+        
+        # Check for required documentation files
+        docs=(
+          "README.md"
+          "CONTRIBUTING.md" 
+          "COPILOT.md"
+          "DEVELOPMENT.md"
+          "CODE_OF_CONDUCT.md"
+          "SECURITY.md"
+          "CHANGELOG.md"
+        )
+        
+        for doc in "${docs[@]}"; do
+          if [ ! -f "$doc" ]; then
+            echo "❌ Missing documentation file: $doc"
+            exit 1
+          fi
+          
+          # Check file is not empty
+          if [ ! -s "$doc" ]; then
+            echo "❌ Documentation file is empty: $doc"
+            exit 1
+          fi
+          
+          echo "✅ Found and validated: $doc"
+        done
+        
+    - name: Validate GitHub templates
+      run: |
+        echo "Checking GitHub issue and PR templates..."
+        
+        templates=(
+          ".github/ISSUE_TEMPLATE/bug_report.yml"
+          ".github/ISSUE_TEMPLATE/feature_request.yml"
+          ".github/ISSUE_TEMPLATE/iiif_compatibility.yml"
+          ".github/ISSUE_TEMPLATE/config.yml"
+          ".github/PULL_REQUEST_TEMPLATE.md"
+        )
+        
+        for template in "${templates[@]}"; do
+          if [ ! -f "$template" ]; then
+            echo "❌ Missing template: $template"
+            exit 1
+          fi
+          echo "✅ Found template: $template"
+        done
+
+  accessibility-check:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      
+    - name: Check HTML accessibility features
+      run: |
+        echo "Checking HTML for accessibility features..."
+        
+        # Check for semantic HTML elements
+        if ! grep -q 'role=' index.html; then
+          echo "⚠️  Consider adding ARIA roles to HTML elements"
+        fi
+        
+        # Check for aria-label usage
+        if grep -q 'aria-label' index.html; then
+          echo "✅ Found ARIA labels"
+        else
+          echo "⚠️  Consider adding ARIA labels for better accessibility"
+        fi
+        
+        # Check for proper heading structure
+        if grep -q '<h[1-6]' index.html; then
+          echo "✅ Found heading elements"
+        else
+          echo "⚠️  Consider adding heading elements for better structure"
+        fi
+        
+        echo "Accessibility check completed"
\ No newline at end of file
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
new file mode 100644
index 0000000..a5101d1
--- /dev/null
+++ b/.github/workflows/deploy.yml
@@ -0,0 +1,187 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+        
+      - name: Create deployment directory
+        run: |
+          mkdir -p _site
+          
+      - name: Copy files to deployment directory
+        run: |
+          # Copy main application files
+          cp index.html _site/
+          cp viewer.js _site/
+          cp iiif-data-service.js _site/
+          cp ui-manager.js _site/
+          cp message-handler.js _site/
+          cp styles.css _site/
+          
+          # Copy documentation
+          cp README.md _site/
+          cp CONTRIBUTING.md _site/
+          cp COPILOT.md _site/
+          cp DEVELOPMENT.md _site/
+          cp CODE_OF_CONDUCT.md _site/
+          cp SECURITY.md _site/
+          cp CHANGELOG.md _site/
+          cp LICENSE _site/
+          
+          # Copy GitHub templates (for reference)
+          mkdir -p _site/.github
+          cp -r .github/ISSUE_TEMPLATE _site/.github/
+          cp .github/PULL_REQUEST_TEMPLATE.md _site/.github/
+          
+      - name: Create demo page
+        run: |
+          cat > _site/demo.html << 'EOF'
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+              <meta charset="UTF-8">
+              <meta name="viewport" content="width=device-width, initial-scale=1.0">
+              <title>IIIF Page Viewer Demo</title>
+              <style>
+                  body {
+                      font-family: Arial, sans-serif;
+                      max-width: 1200px;
+                      margin: 0 auto;
+                      padding: 20px;
+                      line-height: 1.6;
+                  }
+                  .demo-section {
+                      margin: 2rem 0;
+                      padding: 1rem;
+                      border: 1px solid #ddd;
+                      border-radius: 5px;
+                  }
+                  iframe {
+                      width: 100%;
+                      height: 500px;
+                      border: 1px solid #ccc;
+                      border-radius: 3px;
+                  }
+                  .manifest-url {
+                      background: #f5f5f5;
+                      padding: 10px;
+                      border-radius: 3px;
+                      font-family: monospace;
+                      word-break: break-all;
+                      margin: 10px 0;
+                  }
+                  .load-button {
+                      background: #007cba;
+                      color: white;
+                      border: none;
+                      padding: 10px 15px;
+                      border-radius: 3px;
+                      cursor: pointer;
+                      margin: 5px;
+                  }
+                  .load-button:hover {
+                      background: #005a87;
+                  }
+              </style>
+          </head>
+          <body>
+              <h1>IIIF Page Viewer Demo</h1>
+              
+              <p>This demo shows the IIIF Page Viewer in action with real IIIF manifests from cultural institutions.</p>
+              
+              <div class="demo-section">
+                  <h2>Live Demo</h2>
+                  <p>Click the buttons below to load different IIIF manifests:</p>
+                  
+                  <button class="load-button" onclick="loadManifest('https://iiif.io/api/presentation/3.0/example/fixtures/001/manifest.json')">
+                      Load Example IIIF v3 Manifest
+                  </button>
+                  
+                  <button class="load-button" onclick="loadManifest('https://iiif.library.nulib.northwestern.edu/iiif/2/180682d0-4d51-0132-412f-0050569601ca-8/manifest.json')">
+                      Load Northwestern University Manuscript
+                  </button>
+                  
+                  <div class="manifest-url" id="current-manifest">
+                      No manifest loaded
+                  </div>
+                  
+                  <iframe id="viewer-iframe" src="index.html"></iframe>
+              </div>
+              
+              <div class="demo-section">
+                  <h2>How to Use</h2>
+                  <ol>
+                      <li>Click one of the demo buttons above to load a IIIF manifest</li>
+                      <li>Interact with the image (zoom, pan if supported)</li>
+                      <li>Click on annotation overlays to see detailed information</li>
+                      <li>Use keyboard navigation (Tab, Enter, Space) for accessibility</li>
+                  </ol>
+              </div>
+              
+              <div class="demo-section">
+                  <h2>Integration Example</h2>
+                  <p>To embed this viewer in your own website:</p>
+                  <pre><code>&lt;iframe src="https://centerfordigitalhumanities.github.io/Page-Viewer/?canvas=YOUR_MANIFEST_URL" 
+          width="800" 
+          height="600"&gt;&lt;/iframe&gt;</code></pre>
+              </div>
+              
+              <div class="demo-section">
+                  <h2>Documentation</h2>
+                  <ul>
+                      <li><a href="README.md">README</a> - Project overview and usage</li>
+                      <li><a href="CONTRIBUTING.md">Contributing Guide</a> - How to contribute</li>
+                      <li><a href="COPILOT.md">AI Development Guide</a> - Guide for AI assistants</li>
+                      <li><a href="DEVELOPMENT.md">Development Guide</a> - Detailed development setup</li>
+                      <li><a href="https://github.com/CenterForDigitalHumanities/Page-Viewer">GitHub Repository</a></li>
+                  </ul>
+              </div>
+              
+              <script>
+                  function loadManifest(manifestUrl) {
+                      const iframe = document.getElementById('viewer-iframe');
+                      const manifestDisplay = document.getElementById('current-manifest');
+                      
+                      iframe.src = 'index.html?canvas=' + encodeURIComponent(manifestUrl);
+                      manifestDisplay.textContent = 'Current manifest: ' + manifestUrl;
+                  }
+              </script>
+          </body>
+          </html>
+          EOF
+          
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
\ No newline at end of file