Skip to content

Developer Documentation

Jump to bottom
Jones edited this page Jun 24, 2026 · 1 revision

Mango IIIF Viewer: Developer Documentation

1. Project Architecture & Workspace Structure

A clear overview of the codebase organization helps new developers understand where to write code and how components interact.

Key Content to Document:

  • The Monorepo/Workspace Layout:
    • src/lib: The core viewer library source.
    • apps/demo: Local HTML test playground utilizing compiled artifacts.
  • Core Codebase Subdirectories:
    • src/lib/core: Core TypeScript type declarations (ViewerPlugin, ViewerApi, ViewerConfig) and foundational modules (i18n, state).
    • src/lib/components: Top-level Svelte entry components (Viewer.svelte, ViewerElement.svelte).
    • src/lib/features: Panel stacks, layout presets, and page workspaces.
    • src/lib/renderers: Multi-format media renderers (OpenSeadragon, PDF.js, Model Viewer, Audio, Video).
    • src/lib/plugins: Core first-party plugins (Hello Panel, Annotation Focus, Story Builder).

2. Languages & Internationalization (i18n)

Documenting how the viewer handles multiple languages enables contributors to fix translation bugs and localize the viewer for new regions.

Key Content to Document:

  • Locale Files: Detail the JSON structure in src/locales (supporting English en.json, Spanish es.json, French fr.json, and Welsh cy.json).
  • Translation Pipeline: Document the lookup mechanism in i18n.ts:
    • locale: The writable Svelte store storing the active language.
    • t: The derived Svelte store providing reactive key-lookup functions.
    • translate(key, params): The core lookup utility supporting variable replacements (e.g. {index}).
  • Adding a New Language: Walkthrough on creating a translation JSON file, importing it into i18n.ts, and adding its key to supportedLocales.

3. Entry Points & Bundle Optimization

Explain the compilation strategy to ensure developers maintain the codebase's performance and low bundle-size footprint.

Key Content to Document:

  • Entry-Point Structure: Detail the split exports in package.json:
    • viewer.js: Core read-only IIIF viewer.
    • annotation-editor.js: Drawing and editing annotation layers.
    • story-viewer.js: Interactive story playback.
    • story-builder.js: Full storytelling authoring suite.
  • Lazy Rendering Engine: Explain how renderers dynamically import heavy dependencies:
    • OSDViewer.svelte dynamically imports openseadragon.
    • PdfRenderer.svelte dynamically imports pdfjs-dist.
    • ModelRenderer.svelte chunked separately to lazy-load @google/model-viewer.
  • Loader Mechanism: Explain how element.js acts as a tiny custom-element wrapper (<mango-viewer>) that dynamically pulls the appropriate mode bundle from the server based on attributes.

4. Stable API & Event Specifications

Integrators need to know how to programmatically control and listen to the viewer from their host applications.

Key Content to Document:

  • The JS API (class Mango): Reference guide for all methods in the exported controller class:
    • Navigation: setCanvasByIndex(index), setCanvasById(id), setManifest(id).
    • Media playback: play(), pause(), seekTo(time).
    • Camera views: setModelPose(pose), setModelOrbit(orbit).
    • Annotations: addAnnotation(data), removeAnnotation(id).
  • The Global Event Bus (on/off): Catalog of all supported events in ViewerEventMap:
    • canvasChange: Triggered on page/canvas navigation.
    • annotationSelect: Triggered when clicking a visual annotation.
    • mediaTimeUpdate: Triggered on audio/video playback ticks.

5. Plugin Development Guide

Enable third-party developers to extend the viewer's layout stacks and feature capabilities.

Key Content to Document:

  • Writing a Svelte/JS Plugin: Detailed specifications of ViewerPlugin and PluginContext.
  • Layout Slot System: How plugins are positioned (left sidebar, right sidebar, bottom drawer, overlay).
  • Dynamic Plugin Specification: How to compile a standalone plugin module and load it at runtime via remote URLs.
  • Theme Styling Interface: Catalog of CSS custom variables (--viewer-panel, --viewer-accent, etc.) to match host application styling.

6. Storytelling JSON Specification

The Story Builder generates a JSON payload representing a media narration. Documenting this structure allows developers to import/export stories between databases.

Key Content to Document:

  • Story Schema: Field descriptions of chapters, narration tracks, audio segments, target coordinates (viewbox/pose), and delay advance thresholds.
  • Story Store Runes: How the internal Svelte 5 state manager (story.svelte.ts) synchronizes chapters and media capture.

7. Testing & Quality Assurance

Document the testing suites so developers can verify their changes do not break existing features.

Key Content to Document:

  • Unit Testing: Run command npm run test using Vitest for testing state stores, parsers, and utility functions.
  • E2E Integration Testing: Run command npm run test:e2e using Playwright to test browser actions, custom-element attributes, and canvas layouts.

Clone this wiki locally