-
+
Parse Lines
diff --git a/interfaces/project/index.html b/interfaces/project/index.html
index 6d2b7d76..2658e46e 100644
--- a/interfaces/project/index.html
+++ b/interfaces/project/index.html
@@ -69,7 +69,7 @@ Project Details
Parse Lines
diff --git a/interfaces/project/index.html b/interfaces/project/index.html
index 6d2b7d76..2658e46e 100644
--- a/interfaces/project/index.html
+++ b/interfaces/project/index.html
@@ -69,7 +69,7 @@ Project Details
+
Parse Lines
diff --git a/interfaces/transcription/index.js b/interfaces/transcription/index.js
index 7ffa514a..4ec91b22 100644
--- a/interfaces/transcription/index.js
+++ b/interfaces/transcription/index.js
@@ -49,6 +49,24 @@ export default class TranscriptionInterface extends HTMLElement {
this.cleanup.onEvent(TPEN.eventDispatcher, 'tpen-transcription-previous-line', () => this.updateLines())
this.cleanup.onEvent(TPEN.eventDispatcher, 'tpen-transcription-next-line', () => this.updateLines())
+ // Listen for canvas resolution failures to show toast
+ this.cleanup.onEvent(TPEN.eventDispatcher, 'tpen-canvas-resolution-failed', (event) => {
+ const { errorType } = event.detail ?? {}
+ let userMessage = 'Failed to load canvas image.'
+ if (errorType === 'not_found') {
+ userMessage = 'Canvas not found. The image may have been moved or deleted.'
+ } else if (errorType === 'unauthorized' || errorType === 'forbidden') {
+ userMessage = 'Access denied to canvas image.'
+ } else if (errorType === 'network') {
+ userMessage = 'Network error loading canvas. Check your connection.'
+ } else if (errorType === 'server_error') {
+ userMessage = 'Server error loading canvas. Please try again later.'
+ } else if (errorType === 'invalid_json' || errorType === 'invalid_type' || errorType === 'missing_id') {
+ userMessage = 'The canvas data is invalid or incomplete.'
+ }
+ TPEN.eventDispatcher.dispatch('tpen-toast', { status: 'error', message: userMessage })
+ })
+
// Listen for navigation messages from tools
this.cleanup.onWindow('message', this.#handleToolMessages.bind(this))
}
@@ -611,10 +629,9 @@ export default class TranscriptionInterface extends HTMLElement {
if (bottomImage) bottomImage.moveUnder(x, y, width, height, topImage)
}
- getImage(project) {
+ async getImage(project) {
const imageCanvas = this.shadowRoot.querySelector('.canvas-image')
let canvasID
- let err = {}
const allPages = project.layers.flatMap(layer => layer.pages)
if (TPEN?.screen?.pageInQuery) {
const matchingPage = allPages.find(
@@ -625,33 +642,25 @@ export default class TranscriptionInterface extends HTMLElement {
canvasID = allPages[0]?.target
}
- fetch(canvasID)
- .then(response => {
- if (response.status === 404) {
- err = { "status": 404, "statusText": "Canvas not found" }
- throw err
- }
- return response.json()
- })
- .then(canvas => {
- // Handle both Presentation API v3 (items) and v2 (images) formats
- const imageId = canvas.items?.[0]?.items?.[0]?.body?.id ?? canvas.images?.[0]?.resource?.id
- if (imageId) {
- imageCanvas.src = imageId
- }
- else {
- err = { "status": 500, "statusText": "Image could not be found in Canvas" }
- throw err
- }
- })
- .catch(error => {
- if (error?.status === 404) {
- imageCanvas.src = "../../assets/images/404_PageNotFound.jpeg"
- }
- else {
- imageCanvas.src = "../../assets/images/noimage.jpg"
- }
- })
+ if (!canvasID) {
+ imageCanvas.src = "../../assets/images/noimage.jpg"
+ return
+ }
+
+ const canvas = await vault.get(canvasID, 'canvas', false, 'transcription-interface')
+ if (!canvas) {
+ // Event already dispatched by vault, show placeholder
+ imageCanvas.src = "../../assets/images/404_PageNotFound.jpeg"
+ return
+ }
+
+ // Handle both Presentation API v3 (items) and v2 (images) formats
+ const imageId = canvas.items?.[0]?.items?.[0]?.body?.id ?? canvas.images?.[0]?.resource?.id ?? canvas.images?.[0]?.resource?.['@id']
+ if (imageId) {
+ imageCanvas.src = imageId
+ } else {
+ imageCanvas.src = "../../assets/images/noimage.jpg"
+ }
}
setCanvasAndSelector(thisLine, page) {
@@ -680,7 +689,13 @@ export default class TranscriptionInterface extends HTMLElement {
// Get canvas from page target even when there are no lines
const { canvasID } = this.setCanvasAndSelector(null, this.#page)
if (!canvasID) return
- const canvas = this.#canvas = await vault.get(canvasID, 'canvas')
+ const canvas = this.#canvas = await vault.get(canvasID, 'canvas', false, 'transcription-interface')
+ if (!canvas) {
+ // Canvas resolution failed - event already dispatched by vault
+ // Show placeholder for the canvas area
+ topImage.setAttribute('region', '0,0,1000,100')
+ return
+ }
// Show full page when there are no lines
const regionValue = `0,0,${canvas?.width ?? 'full'},${(canvas?.height && canvas?.height / 10) ?? 120}`
topImage.canvas = canvasID
@@ -697,7 +712,14 @@ export default class TranscriptionInterface extends HTMLElement {
if (!(thisLine?.body)) thisLine = await vault.get(thisLine, 'annotation', true)
const { canvasID, region } = this.setCanvasAndSelector(thisLine, this.#page)
- const canvas = this.#canvas = await vault.get(canvasID, 'canvas')
+ const canvas = this.#canvas = await vault.get(canvasID, 'canvas', false, 'transcription-interface')
+ if (!canvas) {
+ // Canvas resolution failed - event already dispatched by vault
+ // Use placeholder region dimensions
+ topImage.canvas = canvasID
+ topImage.setAttribute('region', region ?? '0,0,1000,100')
+ return
+ }
const regionValue = region ?? `0,0,${canvas?.width ?? 'full'},${(canvas?.height && canvas?.height / 10) ?? 120}`
topImage.canvas = canvasID
bottomImage.canvas = canvas
diff --git a/js/vault.js b/js/vault.js
index 431bf77d..d401b33c 100644
--- a/js/vault.js
+++ b/js/vault.js
@@ -1,6 +1,11 @@
// Local simulacrum vault for use in client without something like webpack
import TPEN from "../api/TPEN.js"
import { urlFromIdAndType } from "../js/utils.js"
+
+/**
+ * Vault - Client-side caching utility for IIIF resources.
+ * Provides memory and localStorage caching with type-specific validation.
+ */
class Vault {
constructor() {
this.store = new Map()
@@ -18,21 +23,130 @@ class Vault {
return `vault:${itemType}:${id}`
}
- async get(item, itemType, noCache = false) {
+ /**
+ * Creates a standardized canvas error object.
+ * @param {string} errorType - Error type: 'network' | 'server_error' | 'not_found' | 'forbidden' | 'unauthorized' | 'invalid_json' | 'invalid_type' | 'missing_id'
+ * @param {string} message - Human-readable error message
+ * @param {number|null} httpStatus - HTTP status code (if applicable)
+ * @param {string} canvasUri - The canvas URI that failed
+ * @param {string} [component] - Which component triggered the fetch
+ * @returns {Object} Standardized error object
+ */
+ _createCanvasError(errorType, message, httpStatus, canvasUri, component) {
+ return {
+ errorType,
+ message,
+ httpStatus,
+ canvasUri,
+ component
+ }
+ }
+
+ /**
+ * Validates that a fetched object is a valid IIIF Canvas.
+ * Supports both IIIF Presentation API v2 and v3 formats.
+ * @param {Object} canvas - The fetched canvas data
+ * @param {string} uri - The canvas URI (for error reporting)
+ * @returns {Object|null} Error object if invalid, null if valid
+ */
+ _validateCanvas(canvas, uri) {
+ // Check for id (v3: id, v2: @id)
+ const canvasId = canvas?.id ?? canvas?.['@id']
+ if (!canvasId) {
+ return this._createCanvasError('missing_id', 'Canvas has no id field', null, uri)
+ }
+
+ // Check for type (v3: type, v2: @type)
+ const canvasType = canvas?.type ?? canvas?.['@type']
+ if (!canvasType) {
+ return this._createCanvasError('invalid_type', 'Canvas has no type field', null, uri)
+ }
+
+ // Valid Canvas types: 'Canvas' (v3) or 'sc:Canvas' (v2)
+ const validTypes = ['Canvas', 'sc:Canvas']
+ if (!validTypes.includes(canvasType)) {
+ return this._createCanvasError('invalid_type', `Expected Canvas type, got '${canvasType}'`, null, uri)
+ }
+
+ // Check IIIF context - only warn, don't fail
+ const context = canvas?.['@context']
+ if (context) {
+ const validContexts = [
+ 'http://iiif.io/api/presentation/2/context.json',
+ 'https://iiif.io/api/presentation/2/context.json',
+ 'http://iiif.io/api/presentation/3/context.json',
+ 'https://iiif.io/api/presentation/3/context.json'
+ ]
+ const contexts = Array.isArray(context) ? context : [context]
+ const hasValidContext = contexts.some(c => validContexts.includes(c))
+ if (!hasValidContext) {
+ console.warn(`Canvas ${uri} has non-standard IIIF context:`, context)
+ }
+ }
+
+ return null // Valid canvas
+ }
+
+ /**
+ * Dispatches a canvas resolution failure event.
+ * @param {Object} error - The error object from _createCanvasError
+ */
+ _dispatchCanvasError(error) {
+ TPEN.eventDispatcher?.dispatch('tpen-canvas-resolution-failed', error)
+ }
+
+ /**
+ * Maps HTTP status codes to error types.
+ * @param {number} status - HTTP status code
+ * @returns {string} Error type
+ */
+ _httpStatusToErrorType(status) {
+ if (status === 404) return 'not_found'
+ if (status === 401) return 'unauthorized'
+ if (status === 403) return 'forbidden'
+ if (status >= 500) return 'server_error'
+ return 'server_error'
+ }
+
+ /**
+ * Fetches and caches a resource by ID and type.
+ * For canvas type, performs validation and dispatches events on failure.
+ * @param {string|Object} item - Item ID or object with id property
+ * @param {string} itemType - Type of item ('canvas', 'manifest', etc.)
+ * @param {boolean} [noCache=false] - Skip cache lookup
+ * @param {string} [component] - Component name for error reporting (which component triggered the fetch)
+ * @returns {Promise} The fetched resource or null on failure
+ */
+ async get(item, itemType, noCache = false, component) {
const type = this._normalizeType(itemType ?? item?.type ?? item?.['@type'])
const id = this._getId(item)
+ const isCanvas = type === 'canvas'
const typeStore = this.store.get(type)
let result = typeStore?.get(id)
if (result) return result
const cacheKey = this._cacheKey(type, id)
- const cached = localStorage.getItem(cacheKey)
+ let cached
+ try { cached = localStorage.getItem(cacheKey) } catch {}
if (cached && !noCache) {
try {
const parsed = JSON.parse(cached)
+ // Validate cached canvas data
+ if (isCanvas) {
+ const validationError = this._validateCanvas(parsed, id)
+ if (validationError) {
+ validationError.component = component
+ this._dispatchCanvasError(validationError)
+ try { localStorage.removeItem(cacheKey) } catch {}
+ return null
+ }
+ }
this.set(parsed, type)
return parsed
- } catch {}
+ } catch {
+ // Invalid JSON in cache, remove it
+ try { localStorage.removeItem(cacheKey) } catch {}
+ }
}
try {
@@ -42,9 +156,49 @@ class Vault {
layerId: TPEN.screen?.layerInQuery
})
const response = await fetch(uri)
- if (!response.ok) return null
- const data = await response.json()
+ if (!response.ok) {
+ if (isCanvas) {
+ const errorType = this._httpStatusToErrorType(response.status)
+ const error = this._createCanvasError(
+ errorType,
+ `HTTP ${response.status}: ${response.statusText}`,
+ response.status,
+ uri,
+ component
+ )
+ this._dispatchCanvasError(error)
+ }
+ return null
+ }
+
+ let data
+ try {
+ data = await response.json()
+ } catch (jsonError) {
+ if (isCanvas) {
+ const error = this._createCanvasError(
+ 'invalid_json',
+ 'Response is not valid JSON',
+ response.status,
+ uri,
+ component
+ )
+ this._dispatchCanvasError(error)
+ }
+ return null
+ }
+
+ // Validate canvas structure
+ if (isCanvas) {
+ const validationError = this._validateCanvas(data, uri)
+ if (validationError) {
+ validationError.component = component
+ this._dispatchCanvasError(validationError)
+ return null
+ }
+ }
+
const queue = [{ obj: data, depth: 0 }]
const visited = new Set()
@@ -66,7 +220,8 @@ class Vault {
const type = value?.['@type'] ?? value?.type
if (id && type && !visited.has(id)) {
visited.add(id)
- this.get(id, type)
+ // Fire-and-forget for background caching - errors are non-fatal
+ this.get(id, type).catch(() => {})
// Project embedded object to minimal form
const label = value?.label ?? value?.title
obj[key] = { id, type, ...(label && { label }) }
@@ -78,8 +233,18 @@ class Vault {
localStorage.setItem(cacheKey, JSON.stringify(data))
} catch {}
return data
- } catch {
- return
+ } catch (err) {
+ if (isCanvas) {
+ const error = this._createCanvasError(
+ 'network',
+ err.message || 'Network error',
+ null,
+ id,
+ component
+ )
+ this._dispatchCanvasError(error)
+ }
+ return null
}
}
@@ -104,16 +269,18 @@ class Vault {
if (!typeStore.has(id)) return
typeStore.delete(id)
const cacheKey = this._cacheKey(type, id)
- localStorage.removeItem(cacheKey)
+ try { localStorage.removeItem(cacheKey) } catch {}
}
clear(itemType) {
const type = this._normalizeType(itemType)
- for (const key of Object.keys(localStorage)) {
- if (key.startsWith(`vault:${type}:`)) {
- localStorage.removeItem(key)
+ try {
+ for (const key of Object.keys(localStorage)) {
+ if (key.startsWith(`vault:${type}:`)) {
+ localStorage.removeItem(key)
+ }
}
- }
+ } catch {}
this.store.delete(type)
}
Parse Lines
diff --git a/interfaces/transcription/index.js b/interfaces/transcription/index.js
index 7ffa514a..4ec91b22 100644
--- a/interfaces/transcription/index.js
+++ b/interfaces/transcription/index.js
@@ -49,6 +49,24 @@ export default class TranscriptionInterface extends HTMLElement {
this.cleanup.onEvent(TPEN.eventDispatcher, 'tpen-transcription-previous-line', () => this.updateLines())
this.cleanup.onEvent(TPEN.eventDispatcher, 'tpen-transcription-next-line', () => this.updateLines())
+ // Listen for canvas resolution failures to show toast
+ this.cleanup.onEvent(TPEN.eventDispatcher, 'tpen-canvas-resolution-failed', (event) => {
+ const { errorType } = event.detail ?? {}
+ let userMessage = 'Failed to load canvas image.'
+ if (errorType === 'not_found') {
+ userMessage = 'Canvas not found. The image may have been moved or deleted.'
+ } else if (errorType === 'unauthorized' || errorType === 'forbidden') {
+ userMessage = 'Access denied to canvas image.'
+ } else if (errorType === 'network') {
+ userMessage = 'Network error loading canvas. Check your connection.'
+ } else if (errorType === 'server_error') {
+ userMessage = 'Server error loading canvas. Please try again later.'
+ } else if (errorType === 'invalid_json' || errorType === 'invalid_type' || errorType === 'missing_id') {
+ userMessage = 'The canvas data is invalid or incomplete.'
+ }
+ TPEN.eventDispatcher.dispatch('tpen-toast', { status: 'error', message: userMessage })
+ })
+
// Listen for navigation messages from tools
this.cleanup.onWindow('message', this.#handleToolMessages.bind(this))
}
@@ -611,10 +629,9 @@ export default class TranscriptionInterface extends HTMLElement {
if (bottomImage) bottomImage.moveUnder(x, y, width, height, topImage)
}
- getImage(project) {
+ async getImage(project) {
const imageCanvas = this.shadowRoot.querySelector('.canvas-image')
let canvasID
- let err = {}
const allPages = project.layers.flatMap(layer => layer.pages)
if (TPEN?.screen?.pageInQuery) {
const matchingPage = allPages.find(
@@ -625,33 +642,25 @@ export default class TranscriptionInterface extends HTMLElement {
canvasID = allPages[0]?.target
}
- fetch(canvasID)
- .then(response => {
- if (response.status === 404) {
- err = { "status": 404, "statusText": "Canvas not found" }
- throw err
- }
- return response.json()
- })
- .then(canvas => {
- // Handle both Presentation API v3 (items) and v2 (images) formats
- const imageId = canvas.items?.[0]?.items?.[0]?.body?.id ?? canvas.images?.[0]?.resource?.id
- if (imageId) {
- imageCanvas.src = imageId
- }
- else {
- err = { "status": 500, "statusText": "Image could not be found in Canvas" }
- throw err
- }
- })
- .catch(error => {
- if (error?.status === 404) {
- imageCanvas.src = "../../assets/images/404_PageNotFound.jpeg"
- }
- else {
- imageCanvas.src = "../../assets/images/noimage.jpg"
- }
- })
+ if (!canvasID) {
+ imageCanvas.src = "../../assets/images/noimage.jpg"
+ return
+ }
+
+ const canvas = await vault.get(canvasID, 'canvas', false, 'transcription-interface')
+ if (!canvas) {
+ // Event already dispatched by vault, show placeholder
+ imageCanvas.src = "../../assets/images/404_PageNotFound.jpeg"
+ return
+ }
+
+ // Handle both Presentation API v3 (items) and v2 (images) formats
+ const imageId = canvas.items?.[0]?.items?.[0]?.body?.id ?? canvas.images?.[0]?.resource?.id ?? canvas.images?.[0]?.resource?.['@id']
+ if (imageId) {
+ imageCanvas.src = imageId
+ } else {
+ imageCanvas.src = "../../assets/images/noimage.jpg"
+ }
}
setCanvasAndSelector(thisLine, page) {
@@ -680,7 +689,13 @@ export default class TranscriptionInterface extends HTMLElement {
// Get canvas from page target even when there are no lines
const { canvasID } = this.setCanvasAndSelector(null, this.#page)
if (!canvasID) return
- const canvas = this.#canvas = await vault.get(canvasID, 'canvas')
+ const canvas = this.#canvas = await vault.get(canvasID, 'canvas', false, 'transcription-interface')
+ if (!canvas) {
+ // Canvas resolution failed - event already dispatched by vault
+ // Show placeholder for the canvas area
+ topImage.setAttribute('region', '0,0,1000,100')
+ return
+ }
// Show full page when there are no lines
const regionValue = `0,0,${canvas?.width ?? 'full'},${(canvas?.height && canvas?.height / 10) ?? 120}`
topImage.canvas = canvasID
@@ -697,7 +712,14 @@ export default class TranscriptionInterface extends HTMLElement {
if (!(thisLine?.body)) thisLine = await vault.get(thisLine, 'annotation', true)
const { canvasID, region } = this.setCanvasAndSelector(thisLine, this.#page)
- const canvas = this.#canvas = await vault.get(canvasID, 'canvas')
+ const canvas = this.#canvas = await vault.get(canvasID, 'canvas', false, 'transcription-interface')
+ if (!canvas) {
+ // Canvas resolution failed - event already dispatched by vault
+ // Use placeholder region dimensions
+ topImage.canvas = canvasID
+ topImage.setAttribute('region', region ?? '0,0,1000,100')
+ return
+ }
const regionValue = region ?? `0,0,${canvas?.width ?? 'full'},${(canvas?.height && canvas?.height / 10) ?? 120}`
topImage.canvas = canvasID
bottomImage.canvas = canvas
diff --git a/js/vault.js b/js/vault.js
index 431bf77d..d401b33c 100644
--- a/js/vault.js
+++ b/js/vault.js
@@ -1,6 +1,11 @@
// Local simulacrum vault for use in client without something like webpack
import TPEN from "../api/TPEN.js"
import { urlFromIdAndType } from "../js/utils.js"
+
+/**
+ * Vault - Client-side caching utility for IIIF resources.
+ * Provides memory and localStorage caching with type-specific validation.
+ */
class Vault {
constructor() {
this.store = new Map()
@@ -18,21 +23,130 @@ class Vault {
return `vault:${itemType}:${id}`
}
- async get(item, itemType, noCache = false) {
+ /**
+ * Creates a standardized canvas error object.
+ * @param {string} errorType - Error type: 'network' | 'server_error' | 'not_found' | 'forbidden' | 'unauthorized' | 'invalid_json' | 'invalid_type' | 'missing_id'
+ * @param {string} message - Human-readable error message
+ * @param {number|null} httpStatus - HTTP status code (if applicable)
+ * @param {string} canvasUri - The canvas URI that failed
+ * @param {string} [component] - Which component triggered the fetch
+ * @returns {Object} Standardized error object
+ */
+ _createCanvasError(errorType, message, httpStatus, canvasUri, component) {
+ return {
+ errorType,
+ message,
+ httpStatus,
+ canvasUri,
+ component
+ }
+ }
+
+ /**
+ * Validates that a fetched object is a valid IIIF Canvas.
+ * Supports both IIIF Presentation API v2 and v3 formats.
+ * @param {Object} canvas - The fetched canvas data
+ * @param {string} uri - The canvas URI (for error reporting)
+ * @returns {Object|null} Error object if invalid, null if valid
+ */
+ _validateCanvas(canvas, uri) {
+ // Check for id (v3: id, v2: @id)
+ const canvasId = canvas?.id ?? canvas?.['@id']
+ if (!canvasId) {
+ return this._createCanvasError('missing_id', 'Canvas has no id field', null, uri)
+ }
+
+ // Check for type (v3: type, v2: @type)
+ const canvasType = canvas?.type ?? canvas?.['@type']
+ if (!canvasType) {
+ return this._createCanvasError('invalid_type', 'Canvas has no type field', null, uri)
+ }
+
+ // Valid Canvas types: 'Canvas' (v3) or 'sc:Canvas' (v2)
+ const validTypes = ['Canvas', 'sc:Canvas']
+ if (!validTypes.includes(canvasType)) {
+ return this._createCanvasError('invalid_type', `Expected Canvas type, got '${canvasType}'`, null, uri)
+ }
+
+ // Check IIIF context - only warn, don't fail
+ const context = canvas?.['@context']
+ if (context) {
+ const validContexts = [
+ 'http://iiif.io/api/presentation/2/context.json',
+ 'https://iiif.io/api/presentation/2/context.json',
+ 'http://iiif.io/api/presentation/3/context.json',
+ 'https://iiif.io/api/presentation/3/context.json'
+ ]
+ const contexts = Array.isArray(context) ? context : [context]
+ const hasValidContext = contexts.some(c => validContexts.includes(c))
+ if (!hasValidContext) {
+ console.warn(`Canvas ${uri} has non-standard IIIF context:`, context)
+ }
+ }
+
+ return null // Valid canvas
+ }
+
+ /**
+ * Dispatches a canvas resolution failure event.
+ * @param {Object} error - The error object from _createCanvasError
+ */
+ _dispatchCanvasError(error) {
+ TPEN.eventDispatcher?.dispatch('tpen-canvas-resolution-failed', error)
+ }
+
+ /**
+ * Maps HTTP status codes to error types.
+ * @param {number} status - HTTP status code
+ * @returns {string} Error type
+ */
+ _httpStatusToErrorType(status) {
+ if (status === 404) return 'not_found'
+ if (status === 401) return 'unauthorized'
+ if (status === 403) return 'forbidden'
+ if (status >= 500) return 'server_error'
+ return 'server_error'
+ }
+
+ /**
+ * Fetches and caches a resource by ID and type.
+ * For canvas type, performs validation and dispatches events on failure.
+ * @param {string|Object} item - Item ID or object with id property
+ * @param {string} itemType - Type of item ('canvas', 'manifest', etc.)
+ * @param {boolean} [noCache=false] - Skip cache lookup
+ * @param {string} [component] - Component name for error reporting (which component triggered the fetch)
+ * @returns {Promise