Vaulting

[cubap]

This pull request introduces a major refactor across multiple components to standardize and improve how IIIF resources (such as canvases, manifests, and annotation pages) are fetched and hydrated. The new approach replaces direct network requests with a centralized vault utility, which caches and handles resource resolution, including fallback logic to hydrate missing resources from project manifests. This results in more robust error handling, improved performance through caching, and consistent resource access patterns.

Resource fetching and hydration improvements:

• Replaced direct fetch calls with vault.get for canvases, annotation pages, manifests, and related IIIF resources in all relevant components (e.g., line-parser.js, plain.js, default-transcribe/index.js, column-selector/index.js, continue-working/index.js, read-only-transcribe/index.js, simple-transcription/index.js, transcription-block/index.js, transcription/index.js, line-image/index.js). This ensures resources are cached and resolved consistently. [1] [2] [3] [4] [5] [6]

• Added fallback logic to hydrate missing resources: if a resource isn't found in the cache, the code attempts to prefetch project manifests using vault.prefetchDocuments, then retries the resource fetch. This pattern is now used throughout the codebase for canvases and annotation pages. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]

Error handling and user feedback:

• Improved error handling and user feedback for unresolved resources: components now display user-friendly messages or fallback images when canvases or annotation pages cannot be resolved, instead of throwing raw errors or leaving the UI blank. [1] [2] [3] [4] [5]

Codebase consistency and maintainability:

• Centralized IIIF resource access by importing the shared vault utility in all relevant files, removing redundant instantiations and direct fetch logic. [1] [2] [3] [4] [5]

• Updated urlFromIdAndType in js/utils.js to return empty strings for IIIF resource types (canvas, manifest, collection) that should not be constructed as internal URLs, preventing erroneous fetch attempts.

Minor improvements:

• Fixed a typo in a comment ("recieve" → "receive") for clarity.

These changes collectively make the application more resilient, performant, and maintainable when working with IIIF resources.

[github-actions]

🚀 Deployed on https://69897403d3572eb66aef00cd--tpen-interfaces-preview.netlify.app

[cubap]

This is intended to replace #434 and #435 closing the features connected there.

[Copilot]

Pull request overview

This PR refactors IIIF resource resolution across the UI by routing canvas/manifest/annotation-page fetching through a shared vault utility, aiming to standardize hydration, caching, and fallback behavior (e.g., prefetching manifests to resolve embedded resources).

Changes:

• Enhanced js/vault.js with in-flight de-duping, deeper hydration logic, and a prefetchDocuments() helper.
• Updated multiple components/interfaces to replace direct fetch() usage with vault.get() plus manifest-prefetch fallback logic.
• Adjusted urlFromIdAndType() to avoid constructing internal URLs for IIIF resource types like canvases/manifests/collections.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
js/vault.js	Adds in-flight request de-duping, hydration traversal, and manifest prefetch helper.
js/utils.js	Prevents internal URL construction for IIIF canvas/manifest/collection IDs.
interfaces/transcription/index.js	Switches image/canvas/page resolution to vault.get() with manifest-prefetch fallback.
components/transcription-block/index.js	Uses vault.get() + prefetch fallback for annotation pages.
components/simple-transcription/index.js	Uses vault.get() + prefetch fallback for pages/canvases; minor state cleanup.
components/read-only-transcribe/index.js	Replaces manifest fetch() with vault.get() for static manifest loading.
components/line-image/index.js	Resolves canvases via vault.get() on canvas-change events.
components/legacy-annotator/plain.js	Resolves annotation pages/canvases via vault.get() with manifest-prefetch fallback.
components/default-transcribe/index.js	Replaces external Vault usage with shared vault and resolves annotations/resources via vault.get().
components/continue-working/index.js	Resolves canvases via vault.get() with manifest-prefetch fallback.
components/column-selector/index.js	Resolves annotation pages via vault.get() with manifest-prefetch fallback.
components/annotorious-annotator/line-parser.js	Uses shared vault for canvas resolution; fixes a comment typo.

Comments suppressed due to low confidence (1)

components/default-transcribe/index.js:91

• After the two vault.get attempts, lineElem.line can still be null/undefined, but the code unconditionally dereferences lineElem.line.body[0] and lineElem.line.target..., which will throw and abort rendering the whole page. Add a guard/skip for lines that fail to resolve (and optionally surface a user-facing message).

            lineElem.line = await vault.get(l.id, 'annotation')
            if (!lineElem.line) {
                lineElem.line = await vault.get(l.id, 'annotation', true)
            }
            lineElem.line.body[0] = await vault.get(lineElem.line.body[0].id, 'contentresource')
            lineElem.setAttribute('tpen-line-id', l.id)
            lineImg.setAttribute('tpen-line-id', l.id)
            lineImg.setAttribute('iiif-canvas', lineElem.line.target.source.id)
            lineImg.setAttribute('region', lineElem.line.target.selector.value)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

@cubap I've opened a new pull request, #437, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

@cubap I've opened a new pull request, #438, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

@cubap I've opened a new pull request, #439, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

@cubap I've opened a new pull request, #440, to work on those changes. Once the pull request is ready, I'll request review from you.

[cubap]

Worth noting:

This does not have anywhere yet it uses the "force" parameter that may be wanted for loading pages and layers that we expect will be overwritten. The tests on this so far were just to meet the tester demo.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

_normalizeType preserves IIIF v2 prefixes (e.g., sc:Canvas → sc:canvas). That means resources fetched from v2 endpoints will be cached under sc:* buckets, but most callers request unprefixed types ('canvas', 'manifest'), so cache hits and getWithFallback() after prefetchManifests() can fail to resolve embedded v2 resources. Consider canonicalizing v2 prefixes (e.g., strip sc: / oa: in _normalizeType, and map oa:annotationlist to annotationpage) so lookups work across v2/v3 consistently.

Suggested change

	return (type ?? '').toString().toLowerCase() || 'none'
	// Normalize IIIF types across Presentation API v2 (prefixed) and v3 (unprefixed)
	// Examples:
	// "Canvas" -> "canvas"
	// "sc:Canvas" -> "canvas"
	// "oa:AnnotationList" -> "annotationpage"
	const raw = (type ?? '').toString().trim().toLowerCase()
	if (!raw) return 'none'
	// Strip common IIIF v2 prefixes (Shared Canvas / Open Annotation)
	let normalized = raw
	if (normalized.startsWith('sc:') || normalized.startsWith('oa:')) {
	normalized = normalized.slice(normalized.indexOf(':') + 1)
	}
	// Map v2-specific type names to their v3 canonical equivalents
	if (normalized === 'annotationlist') {
	normalized = 'annotationpage'
	}
	return normalized

[Copilot]

This loop fetches canvases sequentially (await inside for...of). For manifests with many canvases, this will be noticeably slower even with caching. Consider resolving all canvases concurrently (e.g., Promise.all(manifest.items.map(ref => vault.get(ref, 'canvas')))), then iterating over the resolved results.

[Copilot]

The Auto Parse click handler immediately returns before the try block, leaving a large unreachable block of code registered on every render. If the feature is intentionally disabled, it would be clearer to not register the listener (and/or hide/remove the button) behind a feature flag; otherwise remove the early return so the handler can run.

Suggested change

return

[thehabes]

nah it's supposed to be dead like that for now until we want to use it.