Project Structure

Mango Project Structure

This document outlines the codebase organisation and directory structure of the Mango IIIF Viewer repository.

---

1. Directory Tree Overview

Mango/
├── apps/
│   └── demo/                     # Local test playground (standalone HTML pages)
├── docs/                         # Developer documentation and guides
├── scripts/                      # Build-related automation scripts
└── src/
    └── lib/                      # Primary source code of the viewer
        ├── components/           # Svelte UI entry points (Viewer, ViewerElement)
        ├── config/               # Configuration parsing and normalisation
        ├── core/                 # Shared types, event maps, i18n, and core model states
        ├── elements/             # Web Component registration entries
        ├── events/               # Event bus publishers
        ├── features/             # Feature UI panels and layouts
        ├── plugins/              # Plugin slots, registry, and first-party plugins
        ├── renderers/            # Media rendering components (OSD, PDF, 3D, Audio, Video)
        ├── state/                # State management and runes
        └── story/                # Narration, timeline, and authoring logics

---

2. Directory Details

apps/demo

Contains several lightweight HTML pages (viewer.html, story-builder.html, annotation-editor.html, etc.) mapped to compiled script entries in src/dist. This is the sandbox used during local development (npm run dev).

src/lib/components

Contains:

• Viewer.svelte: The main Svelte component. It decides layout configuration, binds API methods, and passes down state.
• ViewerElement.svelte: The Web Component (Custom Element wrapper) that maps HTML properties to Svelte props and handles dynamic loading of plugins/feature modes.

src/lib/core

Houses core system definitions:

• src/lib/core/types: Strongly-typed schemas for configurations, events, plugins, and storytelling.
• src/lib/core/i18n.ts: Writable locale stores and key-lookup engines.

src/lib/features

Contains component layouts for distinct workspaces:

• viewer/ViewerLayout.svelte: Main interface rendering the left toolbar, sidebars, stages, and bottom controls.
• storytelling/: Narration panels and narration audio overlays.

src/lib/renderers

Implements specific media engines corresponding to IIIF canvas types:

• OSDViewer.svelte: Large image loading using OpenSeadragon.
• PdfRenderer.svelte: Documents using PDFJS.
• ModelRenderer.svelte: 3D models using @google/model-viewer.
• AudioRenderer.svelte & VideoRenderer.svelte: Media element streaming.

src/lib/plugins

Contains layout registries and custom panel slots:

• registry.ts: Register and manage active layout modifications.
• PluginPanel.svelte & PluginSlot.svelte: Bind DOM slots for first-party/third-party plugins.