# eXeLearning — Full Documentation Bundle

> This is a single-file concatenation of the eXeLearning ELPX-format
> documentation set, plus the project's architecture and conventions
> documents. It is generated by `scripts/build-llms-full.sh` from the
> Markdown sources under `doc/`. Use this file when a context window
> prefers one large document over following links from `/llms.txt`.

> Source files (in order):
> - `doc/elpx-format.md`
> - `doc/elpx-format/container.md`
> - `doc/elpx-format/content-xml.md`
> - `doc/elpx-format/ids.md`
> - `doc/elpx-format/metadata.md`
> - `doc/elpx-format/pages-blocks.md`
> - `doc/elpx-format/idevices/catalog.md`
> - `doc/elpx-format/idevices/patterns.md`
> - `doc/elpx-format/idevices/config-xml.md`
> - `doc/elpx-format/idevices/snippets.md`
> - `doc/elpx-format/themes.md`
> - `doc/elpx-format/libraries.md`
> - `doc/elpx-format/assets.md`
> - `doc/elpx-format/screenshot.md`
> - `doc/elpx-format/export-pipeline.md`
> - `doc/elpx-format/import-pipeline.md`
> - `doc/elpx-format/validation.md`
> - `doc/elpx-format/ai-generation.md`
> - `doc/elpx-format/examples/minimal-content-xml.md`
> - `doc/elpx-format/examples/multi-page-content-xml.md`
> - `doc/elpx-format/examples/full-package-tree.md`
> - `doc/architecture.md`
> - `doc/conventions.md`

---


# ===== doc/elpx-format.md =====

# ELPX Format Documentation

This is the hub for the `.elpx` file format used by eXeLearning v3+. The format is documented across a focused subdoc set under [`doc/elpx-format/`](elpx-format/) — start here, then jump to the specific reference you need.

> **For AI / LLM agents**: read [`elpx-format/ai-generation.md`](elpx-format/ai-generation.md) first, then the [`/llms.txt`](../llms.txt) index at the repo root, then the subdocs cited from each.

> **For the legacy `.elp` format** (eXeLearning 2.x), see [contentv3-format.md](contentv3-format.md).

---

## What is `.elpx`?

An `.elpx` file is a **ZIP archive** containing a complete, self-contained eXeLearning project. It was introduced in eXeLearning v3.0 to replace the legacy Python-pickle `.elp` format. A single `.elpx` carries:

- **`content.xml`** — the project structure in ODE 2.0 XML, validatable against a bundled DTD, re-importable for editing.
- **`index.html` + `html/`** — pre-rendered HTML output, viewable directly in a browser without unpacking.
- **`theme/`, `libs/`, `idevices/`, `content/`** — every CSS, JavaScript, image, font, and asset the rendered content depends on.
- **`screenshot.png`** — 1280×720 PNG project thumbnail at the ZIP root (always present in v4 packages; legacy files without one can be patched with [`scripts/add-screenshot.ts`](../scripts/add-screenshot.ts)).

Because the package contains both the editable source and the rendered output, `.elpx` is the recommended exchange format: human-readable in any browser, re-importable into eXeLearning for editing, and validatable end-to-end.

---

## Quick reference

| Property | Value |
|----------|-------|
| Container | ZIP (deflate) |
| Required root files | `content.xml`, `content.dtd`, `index.html`, `screenshot.png` |
| Required directories | `theme/`, `libs/`, `idevices/<type>/` for each used type |
| Optional root files | `search_index.js` (when search box is enabled) |
| Asset layout | `content/resources/<folderPath>/<filename>` (user folders preserved; legacy v3 UUID subfolders normalised away) |
| Asset reference form | `{{context_path}}/<exportPath>` inside `<htmlView>` / `<jsonProperties>` where `<exportPath>` is `<folderPath>/<filename>` (or just `<filename>` when no folder); `{{context_path}}` resolves to `content/resources/` at render time |
| XML namespace | `http://www.intef.es/xsd/ode` |
| Format version | ODE `2.0` (root `<ode version="2.0">`) |
| Runtime version | constant `ODE_VERSION` = `"3.0"` (XML key `exe_version`) |
| ID format | `[0-9]{14}[A-Z0-9]{6}` |
| iDevice catalog | 43 types (see [catalog](elpx-format/idevices/catalog.md)) |
| Schemas | DTD bundled at root + XSD in repo |

---

## Documentation map

### Container and structure

- **[container.md](elpx-format/container.md)** — every file and directory inside an `.elpx` ZIP, mandatory vs optional, where each entry comes from in the export pipeline.
- **[content-xml.md](elpx-format/content-xml.md)** — full element-by-element reference for `content.xml` (DOCTYPE, root, `<userPreferences>`, `<odeResources>`, `<odeProperties>`, `<odeNavStructures>`, plus the bundled DTD verbatim and pointer to the XSD).
- **[ids.md](elpx-format/ids.md)** — ODE identifier format, generation, lifecycle, cross-hierarchy synchronization rules.
- **[metadata.md](elpx-format/metadata.md)** — every `pp_*` property key, type, default, plus `userPreferences` and `odeResources`.
- **[pages-blocks.md](elpx-format/pages-blocks.md)** — flat-list navigation model, parent-child IDs, ordering, `exe-node:` internal links.

### iDevices

- **[idevices/catalog.md](elpx-format/idevices/catalog.md)** — every iDevice type (modern names, legacy/FPD aliases, downloadable flag, category).
- **[idevices/patterns.md](elpx-format/idevices/patterns.md)** — the four content-storage patterns (Standard JSON, URI-encoded JSON, `<script type="application/json">`, `htmlView`-only) with decision flow.
- **[idevices/config-xml.md](elpx-format/idevices/config-xml.md)** — the per-iDevice `config.xml` schema in `public/files/perm/idevices/base/<type>/`.
- **[idevices/snippets.md](elpx-format/idevices/snippets.md)** — copy-pasteable `<odeComponent>` XML for every type, extracted from real fixtures.

### Resources, themes, assets

- **[themes.md](elpx-format/themes.md)** — theme bundle layout, the 6 in-tree themes (`base`, `flux`, `neo`, `nova`, `universal`, `zen`), per-theme `config.xml`, custom user themes.
- **[libraries.md](elpx-format/libraries.md)** — `libs/` contents and inclusion rules (always-bundled vs conditional, including `common_i18n.js` generation and `elpx-manifest.js`).
- **[assets.md](elpx-format/assets.md)** — the asset URL lifecycle (`asset://` → `{{context_path}}/content/resources/` → relative path).
- **[screenshot.md](elpx-format/screenshot.md)** — root `screenshot.png` spec, dimensions, generation hook, base64 round-trip.

### Pipelines

- **[export-pipeline.md](elpx-format/export-pipeline.md)** — end-to-end export flow with file:line references to `Html5Exporter` / `ElpxExporter` / `OdeXmlGenerator`.
- **[import-pipeline.md](elpx-format/import-pipeline.md)** — three-phase import flow, modern vs legacy fallback, ID remapping.

### Validation and AI generation

- **[validation.md](elpx-format/validation.md)** — DTD vs XSD coverage, mandatory presence checklist, common rejection causes, how to run `xmllint` and `OdeXmlValidator`.
- **[ai-generation.md](elpx-format/ai-generation.md)** — rules and recipes for LLMs producing `.elpx`: the ten non-negotiables, recommended pipeline, pre-flight checklist, prompt-engineering hints.

### Examples

- **[examples/minimal-content-xml.md](elpx-format/examples/minimal-content-xml.md)** — smallest valid `content.xml` (1 page, 1 block, 1 text iDevice) plus a `zip` recipe.
- **[examples/multi-page-content-xml.md](elpx-format/examples/multi-page-content-xml.md)** — hierarchy + multiple iDevices covering all four storage patterns.
- **[examples/full-package-tree.md](elpx-format/examples/full-package-tree.md)** — annotated `unzip -l` of `test/fixtures/really-simple-test-project.elpx`.

---

## ZIP layout at a glance

```
project.elpx (ZIP)
├── content.xml                  # ODE 2.0 project structure (re-importable)
├── content.dtd                  # DTD for XML validation (bundled copy)
├── index.html                   # Entry point (first page rendered as HTML)
├── screenshot.png               # 1280×720 PNG project thumbnail (always present in v4)
├── html/
│   ├── page-title.html          # Additional pages (one file per page)
│   └── ...
├── content/
│   ├── css/
│   │   ├── base.css             # Base stylesheet
│   │   └── icons/*.svg          # ~75 SVG icons used by the eXeLearning runtime UI
│   ├── img/
│   │   └── exe_powered_logo.png
│   └── resources/               # User-uploaded assets (no UUID subfolders in v4)
│       ├── photo.jpg            # asset with no folderPath
│       ├── audio-clip.mp3
│       ├── document.pdf
│       └── photos/              # user-created folder, preserved verbatim
│           └── vacation/sunset.jpg
├── libs/
│   ├── jquery/jquery.min.js
│   ├── bootstrap/bootstrap.bundle.min.js
│   ├── bootstrap/bootstrap.min.css
│   ├── common.js
│   ├── common_i18n.js           # Generated per export language
│   ├── exe_export.js
│   ├── favicon.ico
│   ├── exe_atools/              # Accessibility toolbar (conditional)
│   └── ...                      # Other conditionally-bundled libraries
├── theme/
│   ├── config.xml
│   ├── style.css
│   ├── style.js
│   ├── screenshot.png           # THEME's preview thumbnail (distinct from the project's)
│   ├── icons/
│   └── img/
├── idevices/
│   ├── text/
│   │   ├── text.js
│   │   ├── text.css
│   │   └── text.html
│   └── <type>/                  # One folder per iDevice type used in the project
└── search_index.js              # Optional: present when search box is enabled
```

Detailed mandatory-vs-optional matrix: [container.md](elpx-format/container.md).

---

## Differences from legacy `.elp`

| Aspect | `.elpx` (modern) | `.elp` (legacy) |
|--------|------------------|-----------------|
| Content file | `content.xml` (ODE 2.0) | `contentv3.xml` (Python pickle XML) |
| Root element | `<ode xmlns="...">` | `<instance class="exe.engine.package.Package">` |
| Serialization | Native XML | Python object serialization |
| Hierarchy | Flat list with `odeParentPageId` | Nested `Node` instances |
| Content storage | `<htmlView>` + `<jsonProperties>` (CDATA-wrapped) | `<unicode content="true">` |
| Metadata | `<odeProperty>` elements | Dictionary key-value pairs |
| IDs | `YYYYMMDDHHmmss` + 6 chars | Sequential integers |
| DTD validation | Supported (bundled `content.dtd`) | Not feasible (dynamic structure) |
| Asset paths | `{{context_path}}/content/resources/` | `resources/` |
| HTML output | Included in ZIP | Not included |
| Screenshot | Optional `screenshot.png` at root | None |

For full legacy details, see [contentv3-format.md](contentv3-format.md).

---

## Implementation files (ground-truth code)

| File | Role |
|------|------|
| `src/shared/export/exporters/ElpxExporter.ts` | Builds the ZIP archive (extends `Html5Exporter`) |
| `src/shared/export/exporters/Html5Exporter.ts` | Page generation, theme/library/asset bundling |
| `src/shared/export/exporters/BaseExporter.ts` | Abstract base with `addFilenamesToAssetUrls()` |
| `src/shared/export/generators/OdeXmlGenerator.ts` | Generates `content.xml` from `ExportMetadata` + pages |
| `src/shared/export/metadata-properties.ts` | Single source of truth for `pp_*` property mapping |
| `src/shared/export/constants.ts` | DTD literal, BASE_LIBRARIES, LICENSE_REGISTRY, IDEVICE_TYPE_MAP, LIBRARY_PATTERNS |
| `src/shared/import/ElpxImporter.ts` | Parses `.elpx` and `.elp` files into a Yjs document |
| `src/shared/import/LegacyXmlParser.ts` | Legacy CamelCase type-name remapping for `.elp` files |
| `src/services/xml/xml-parser.ts` | ODE XML parsing helpers |
| `src/services/xml/ode-xml-validator.ts` | DTD/XSD validator |
| `public/app/schemas/ode/content.dtd` | Canonical DTD reference |
| `public/app/schemas/ode/ode-content.xsd` | Stricter XSD with regex-validated IDs and enumerated types |

---

## Test fixtures (real `.elpx` files in this repo)

| Fixture | Use |
|---------|-----|
| `test/fixtures/really-simple-test-project.elpx` | Minimal multi-page project — annotated tree at [examples/full-package-tree.md](elpx-format/examples/full-package-tree.md) |
| `test/fixtures/todos-los-idevices_dos_informes.elpx` | Every iDevice type — primary source for [idevices/snippets.md](elpx-format/idevices/snippets.md) |
| `test/fixtures/Manual de eXeLearning 3.0.elpx` | Full real-world manual covering `text`, `casestudy`, `image-gallery`, `magnifier`, `external-website`, `download-source-file`, `udl-content`, `rubric` |
| `test/fixtures/basic-example-with-custom-theme.elpx` | Custom theme bundling |
| `test/fixtures/arrows.elpx` | Diagram / vector content |

To inspect a fixture: `unzip -l "test/fixtures/<name>.elpx"`. To extract: `unzip -d /tmp/elpx-inspect "test/fixtures/<name>.elpx"`.

---

## See also

- [`/llms.txt`](../llms.txt) — top-level index for LLM consumption (per [llmstxt.org](https://llmstxt.org/))
- [`/llms-full.txt`](../llms-full.txt) — full doc bundle in a single file for LLMs that cannot follow links
- [doc/architecture.md](architecture.md) — system architecture overview
- [doc/conventions.md](conventions.md) — code conventions
- [doc/development/styles.md](development/styles.md) — theme authoring guide
- [doc/development/real-time.md](development/real-time.md) — Yjs and WebSocket model
- [doc/development/rest-api.md](development/rest-api.md) — REST API v1 (external integrations)
- [doc/contentv3-format.md](contentv3-format.md) — legacy `.elp` format


# ===== doc/elpx-format/container.md =====

# ELPX Container: ZIP Structure

An `.elpx` file is a standard ZIP archive produced by `ElpxExporter.ts`. It bundles a complete HTML5 rendition of the project together with a re-importable `content.xml`. This document describes every entry in the archive, where each one comes from, and which entries are required by the importer.

See also: [ELPX format overview](../elpx-format.md) | [IDs](ids.md) | [Pages and blocks](pages-blocks.md) | [Metadata](metadata.md)

---

## Folder tree (fix-simple fixture)

The tree below is extracted from the unzipped fixture at `/tmp/elpx-docs-work/fix-simple/`. Individual icon SVG files in `content/css/icons/` are collapsed for brevity.

```
project.elpx (ZIP)
├── content.xml                      # ODE 2.0 project structure (re-importable)
├── content.dtd                      # DTD for content.xml validation (always bundled in v4)
├── index.html                       # First page rendered as HTML
├── screenshot.png                   # 1280×720 PNG project thumbnail (always present in v4)
├── search_index.js                  # (optional) Search index — only when pp_addSearchBox=true
├── content/
│   ├── css/
│   │   ├── base.css                 # Base stylesheet
│   │   └── icons/                   # … 75 icon SVGs (exe-*.svg, plus.svg, etc.)
│   ├── img/
│   │   └── exe_powered_logo.png
│   └── resources/                   # Project assets — no UUID subfolders in v4
│       ├── photo.jpg                # asset with no folderPath
│       ├── audio-clip.mp3
│       ├── document.pdf
│       └── photos/                  # user-created folder, preserved verbatim
│           └── vacation/sunset.jpg  # nested user folder is fine
├── html/
│   ├── page-1-1.html
│   ├── page-1-1-1.html
│   ├── page-1-2.html
│   ├── page-2.html
│   └── page-2-1.html
├── idevices/
│   └── text/
│       ├── text.css
│       ├── text.html
│       └── text.js
├── libs/
│   ├── bootstrap/
│   │   ├── bootstrap.bundle.min.js
│   │   ├── bootstrap.bundle.min.js.map
│   │   ├── bootstrap.min.css
│   │   └── bootstrap.min.css.map
│   ├── common.js
│   ├── common_i18n.js
│   ├── exe_atools/                  # Accessibility toolbar assets
│   ├── exe_export.js
│   ├── favicon.ico
│   └── jquery/
│       └── jquery.min.js
├── theme/
│   ├── config.xml
│   ├── icons/                       # Theme-specific block icons (PNG)
│   ├── img/
│   │   ├── icons.png
│   │   └── licenses.gif
│   ├── screenshot.png               # Theme preview (not the project screenshot)
│   ├── style.css
│   └── style.js
└── custom/                          # (optional) Custom CSS/JS injected by pp_customStyles
```

---

## Mandatory vs. optional entry matrix

| Entry | Required in ZIP | Required by importer | Notes |
|---|---|---|---|
| `content.xml` | Yes | Yes — mandatory | Missing = import error |
| `content.dtd` | Yes — always bundled in v4 | No | For offline XML validation; emitted by `ElpxExporter` from `ODE_DTD_CONTENT` (`constants.ts:1006`) |
| `index.html` | Yes | No | Pre-rendered first page; ignored on import |
| `screenshot.png` (archive root) | Yes in v4 | No | 1280×720 PNG project thumbnail. Required for v4 packages so external systems (LMS, file managers, repositories) can show a preview. Stored in Yjs `metadata.screenshot` on import. See [screenshot.md](screenshot.md). |
| `html/*.html` | Yes (one per extra page) | No | Pre-rendered pages; ignored on import |
| `content/css/base.css` | Yes | No | Rendering only |
| `content/css/icons/` | Yes | No | Rendering only |
| `content/img/exe_powered_logo.png` | Conditional | No | Added only when `pp_addExeLink` is `true` |
| `content/resources/<filename>` | When project has assets | No | Flat layout. Asset data; importer reads these for `asset://` mapping. See [assets.md](assets.md). |
| `libs/` | Yes | No | jQuery, Bootstrap, i18n scripts |
| `theme/` | Yes | No | Theme CSS/JS; re-applied on export after import |
| `idevices/<type>/` | One per iDevice type used | No | iDevice-specific CSS/JS |
| `custom/` | Optional | No | Written only when `pp_customStyles` is non-empty |
| `search_index.js` | Optional | No | Written only when `pp_addSearchBox` is `true` |

Notes:

- `content/resources/` entries are read by the importer during the asset extraction phase (`importAssets()`), so they are effectively required when the project references any assets. Without them, asset references in `content.xml` will resolve to missing files.
- `content/resources/` mirrors the project's asset folder tree in v4: assets without a `folderPath` live at the root of `content/resources/`, and any user-created folders (e.g. `photos/`, `lesson-1/handouts/`) appear as real subdirectories under the same path. The legacy v3 per-asset UUID subfolder pattern (`content/resources/<14-digit-timestamp><6-char-suffix>/<filename>`) is **not** part of v4 and is normalised by [`scripts/flatten-elpx.ts`](../../scripts/flatten-elpx.ts) (which only collapses folders matching that exact regex; user folders are preserved untouched).
- `screenshot.png` and `content.dtd` are produced for every export by `ElpxExporter`. If you receive a v3-era `.elpx` without one or both, run `scripts/add-screenshot.ts` and re-export through `elp:convert` to bring it up to the v4 baseline.

---

## Where each entry comes from

All ZIP assembly happens in `ElpxExporter.ts`. `ElpxExporter` extends `Html5Exporter`; the HTML rendering pass runs first, then ELPX-specific files are added in a second section.

| Entry | Producer method / location |
|---|---|
| `index.html` | `Html5Exporter` — page render loop, first page is always `index.html` |
| `html/<slug>.html` | `Html5Exporter` — one call per additional page, slug derived from page title |
| `content/css/base.css` | `Html5Exporter` — `addFile('content/css/base.css', baseCss)` |
| `content/css/icons/` | `Html5Exporter` — iterates icon directory from theme assets |
| `content/img/exe_powered_logo.png` | `Html5Exporter` — conditional on `pp_addExeLink` |
| `content/resources/` | `Html5Exporter` — iterates project assets from Yjs `assets` Y.Map |
| `libs/` | `Html5Exporter` — iterates `BASE_LIBRARIES` and detected `LIBRARY_PATTERNS` |
| `theme/` | `Html5Exporter` — iterates active theme files |
| `idevices/<type>/` | `Html5Exporter` — one subdirectory per iDevice type present in the project |
| `search_index.js` | `Html5Exporter` — conditional on `pp_addSearchBox` (`addFile('search_index.js', ...)`) |
| `content.xml` | `ElpxExporter` — `generateOdeXml()` via `OdeXmlGenerator.ts`, then `this.zip.addFile('content.xml', contentXml)` |
| `content.dtd` | `ElpxExporter` — `this.zip.addFile(ODE_DTD_FILENAME, ODE_DTD_CONTENT)` where `ODE_DTD_FILENAME = 'content.dtd'` (`constants.ts:995`) |
| `screenshot.png` (root) | `ElpxExporter` — `this.zip.addFile('screenshot.png', screenshotBuffer)`. v4 always emits one: either the user-set screenshot or a generated thumbnail. |
| `custom/` | `Html5Exporter` — written when `pp_customStyles` is non-empty |

The final ZIP is assembled using JSZip (browser) or a compatible in-process archiver (server). The `ElpxExporter` accumulates all entries via `this.zip.addFile(path, content)` calls and serializes the archive in one step at the end of `export()`.

---

## Re-importable requirement

The importer (`ElpxImporter.ts`) only **strictly** requires:

1. `content.xml` — mandatory. Its absence throws `'content.xml is missing'`.
2. `content/resources/<filename>` — required per asset referenced in `content.xml`. Assets are mapped from `{{context_path}}/<filename>` (or the legacy `{{context_path}}/content/resources/<filename>` form) back to internal `asset://` URIs during the asset extraction phase.
3. `screenshot.png` at the archive root — read when present and stored as a base64 data URL under the `screenshot` metadata key.

In other words a `.elpx` will round-trip into the editor as long as it has `content.xml` plus any referenced assets. HTML files, libraries, theme files, and iDevice assets are not read by the importer and can be absent without error.

That said, for **publication and exchange** the v4 baseline is stricter: every released `.elpx` should carry `content.dtd`, `screenshot.png`, `index.html`, the `theme/`, `libs/`, and `idevices/<type>/` directories so the package is offline-viewable in any browser without a re-import. The exporter always produces this complete set; only round-tripped imports of older v3 fixtures may need to be patched up via [`scripts/add-screenshot.ts`](../../scripts/add-screenshot.ts).

For EPUB3 archives, the importer also handles `EPUB/content.xml` by stripping the `EPUB/` prefix before processing, making the path equivalent to a root-level `content.xml`.

---

## Minimum content for a v4 `.elpx`

The smallest **v4-compliant** package — one that passes validation, opens cleanly in any browser, and re-imports without warnings — must contain at minimum:

```
project.elpx
├── content.xml                  # ODE 2.0 XML, references 'content.dtd' in DOCTYPE
├── content.dtd                  # bundled DTD (constant ODE_DTD_CONTENT)
├── index.html                   # rendered first page
├── screenshot.png               # 1280×720 project thumbnail (PNG)
├── theme/                       # at minimum config.xml + style.css + style.js
├── libs/                        # base libraries (jQuery, Bootstrap, common.js, exe_export.js, common_i18n.js)
└── idevices/<type>/             # CSS/JS for every iDevice type used
```

If `content.xml` references assets, add them under `content/resources/<filename>` (flat). If pages other than `index.html` exist, add `html/<slug>.html` per page.

A package that lacks `screenshot.png` or `content.dtd` will still re-import (the importer is lenient), but it is considered out-of-spec for v4. See [validation.md](validation.md) for the full checklist and [ai-generation.md](ai-generation.md) for an LLM-friendly version.

---

## Compression

`.elpx` is a standard ZIP archive. Compression is handled by JSZip in the browser exporter. The `ElpxExporter` does not set a specific compression level per file; JSZip defaults apply. Binary assets (images, fonts) are stored without re-compression. Text files (`content.xml`, HTML, CSS, JS) benefit from DEFLATE compression.

The archive is finalized with `this.zip.generateAsync({ type: 'uint8array' })` (browser) or the equivalent server-side call in `ElpxExporter.export()`.


# ===== doc/elpx-format/content-xml.md =====

# `content.xml` Reference

Authoritative reference for the ODE 2.0 XML document that lives at the root of every `.elpx` archive. This is the file an importer reads to reconstruct a project.

> **Hub**: [doc/elpx-format.md](../elpx-format.md). Sibling subdocs:
> [container.md](container.md), [ids.md](ids.md), [metadata.md](metadata.md),
> [pages-blocks.md](pages-blocks.md), [idevices/catalog.md](idevices/catalog.md),
> [idevices/patterns.md](idevices/patterns.md), [validation.md](validation.md).

---

## At a glance

| Property | Value |
|----------|-------|
| Filename | `content.xml` (always at ZIP root) |
| Encoding | UTF-8, XML 1.0 |
| Namespace | `http://www.intef.es/xsd/ode` |
| Format version | ODE `2.0` (root attribute `version="2.0"`) |
| Schema | DTD `content.dtd` bundled at ZIP root + XSD `ode-content.xsd` (in repo, not bundled) |
| Top-level elements (in order) | `userPreferences?`, `odeResources?`, `odeProperties?`, `odeNavStructures` |
| Generator | [`src/shared/export/generators/OdeXmlGenerator.ts`](../../src/shared/export/generators/OdeXmlGenerator.ts) |
| Importer | [`src/shared/import/ElpxImporter.ts`](../../src/shared/import/ElpxImporter.ts) + [`src/services/xml/xml-parser.ts`](../../src/services/xml/xml-parser.ts) |

---

## Document declaration

Every `content.xml` produced by [`OdeXmlGenerator.generateOdeXml()`](../../src/shared/export/generators/OdeXmlGenerator.ts) starts with:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ode SYSTEM "content.dtd">
<ode xmlns="http://www.intef.es/xsd/ode" version="2.0">
  ...
</ode>
```

Notes:

- The DOCTYPE filename is the constant `ODE_DTD_FILENAME` (= `"content.dtd"`) defined in [`src/shared/export/constants.ts:995`](../../src/shared/export/constants.ts).
- The DOCTYPE line is omitted only when the same generator is reused for SCORM/IMS exports (option `includeDoctype: false`). For `.elpx` it is always emitted.
- The XML declaration encoding is fixed to `UTF-8`. All text content (page titles, iDevice content, metadata) is UTF-8.
- `xmlns` is fixed by the DTD (`<!ATTLIST ode xmlns CDATA #FIXED "http://www.intef.es/xsd/ode">`); a parser that does not see this exact namespace MUST reject the file.
- `version` is currently `"2.0"`. The string `"3.0"` is the eXeLearning runtime version and lives separately inside `<odeResources>` under the key `exe_version`.

---

## Root `<ode>` element

```dtd
<!ELEMENT ode (userPreferences?, odeResources?, odeProperties?, odeNavStructures)>
<!ATTLIST ode
    xmlns CDATA #FIXED "http://www.intef.es/xsd/ode"
    version CDATA #IMPLIED>
```

| Attribute | Required | Type | Description |
|-----------|----------|------|-------------|
| `xmlns` | Fixed | CDATA | Always `http://www.intef.es/xsd/ode` |
| `version` | Optional | CDATA | ODE format version. Currently `"2.0"`. Reserved for future schema bumps. |

Children in declared order:

| Child | Cardinality | Purpose | Subdoc |
|-------|-------------|---------|--------|
| `<userPreferences>` | 0 or 1 | UI-level preferences. Only `theme` is currently emitted. | [metadata.md#userpreferences](metadata.md) |
| `<odeResources>` | 0 or 1 | Package identifiers and runtime version. | [metadata.md#oderesources](metadata.md) |
| `<odeProperties>` | 0 or 1 | Project metadata (`pp_*` keys). | [metadata.md#odeproperties](metadata.md) |
| `<odeNavStructures>` | exactly 1 | Pages, blocks, components (the actual content tree). | [pages-blocks.md](pages-blocks.md) |

Although the DTD allows `userPreferences`, `odeResources`, `odeProperties` to be absent, the modern generator always emits all four. Importers should tolerate absence and fill with defaults from [`metadata-properties.ts`](../../src/shared/export/metadata-properties.ts).

---

## `<userPreferences>` and `<userPreference>`

Stores UI-level preferences. Currently only the active theme is emitted by the generator at [`OdeXmlGenerator.ts:79`](../../src/shared/export/generators/OdeXmlGenerator.ts):

```xml
<userPreferences>
  <userPreference>
    <key>theme</key>
    <value>base</value>
  </userPreference>
</userPreferences>
```

| Element | Children | Notes |
|---------|----------|-------|
| `<userPreferences>` | `<userPreference>*` | May be empty. |
| `<userPreference>` | `<key>` + `<value>` | Both `#PCDATA`, XML-escaped. |

Recognized keys (currently single):

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `theme` | string | `"base"` | Theme folder name. Must match a folder in `theme/` of the same `.elpx`, or be the name of a built-in theme that the runtime can load. See [themes.md](themes.md). |

The fallback `"base"` is hardcoded in the generator (`meta.theme || 'base'`).

---

## `<odeResources>` and `<odeResource>`

Package-level identifiers and runtime version. Generator at [`OdeXmlGenerator.ts:97`](../../src/shared/export/generators/OdeXmlGenerator.ts):

```xml
<odeResources>
  <odeResource>
    <key>odeId</key>
    <value>20251217061325EKESBR</value>
  </odeResource>
  <odeResource>
    <key>odeVersionId</key>
    <value>20251217061452XKBQML</value>
  </odeResource>
  <odeResource>
    <key>exe_version</key>
    <value>3.0</value>
  </odeResource>
</odeResources>
```

| Key | Type | Lifecycle | Description |
|-----|------|-----------|-------------|
| `odeId` | ODE identifier | Stable per project | Persistent project ID. Set once on creation; survives re-saves and re-exports. |
| `odeVersionId` | ODE identifier | Regenerated every export | Snapshot ID. Changes on every save/export; lets two `.elpx` files of the same project be distinguished. |
| `exe_version` | string | Constant per build | The running eXeLearning runtime version. Constant `ODE_VERSION` = `"3.0"` (see [`constants.ts:1000`](../../src/shared/export/constants.ts)). |

ID format and synchronization rules: see [ids.md](ids.md). Other resource keys observed in older fixtures (e.g. `odeVersionName`, `isDownload`, `eXeVersion`) are tolerated by the importer but **not produced** by the modern generator.

---

## `<odeProperties>` and `<odeProperty>`

Project metadata. Each `<odeProperty>` is a `<key>` / `<value>` pair (both `#PCDATA`, XML-escaped). The generator iterates [`METADATA_PROPERTIES`](../../src/shared/export/metadata-properties.ts) and emits one `<odeProperty>` per non-internal entry that has a non-empty value.

```xml
<odeProperties>
  <odeProperty>
    <key>pp_title</key>
    <value>An Introduction to Photosynthesis</value>
  </odeProperty>
  <odeProperty>
    <key>pp_lang</key>
    <value>en</value>
  </odeProperty>
  <odeProperty>
    <key>pp_addExeLink</key>
    <value>true</value>
  </odeProperty>
  ...
</odeProperties>
```

Boolean values are serialized as the strings `"true"` / `"false"` ([`valueToXmlString`, `metadata-properties.ts:354`](../../src/shared/export/metadata-properties.ts)). HTML/XML payloads (e.g. `pp_extraHeadContent`, `footer`) are XML-escaped via the standard entities — they are NOT wrapped in CDATA inside `<odeProperty>` (CDATA wrapping is reserved for `<htmlView>` and `<jsonProperties>`).

For the full key reference (internal key, XML key, type, default), see [metadata.md](metadata.md). The XSD enumerates the canonical keys at [`ode-content.xsd:255-291`](../../public/app/schemas/ode/ode-content.xsd) (`propertyKeyType`).

---

## `<odeNavStructures>` and the page/block/component tree

The body of the document. A flat list of `<odeNavStructure>` (page) elements, each containing blocks and components. Hierarchy between pages is expressed by `<odeParentPageId>`, **not** by XML nesting.

```dtd
<!ELEMENT odeNavStructures (odeNavStructure*)>
<!ELEMENT odeNavStructure (odePageId, odeParentPageId, pageName, odeNavStructureOrder, odeNavStructureProperties?, odePagStructures?)>
<!ELEMENT odePagStructures (odePagStructure*)>
<!ELEMENT odePagStructure (odePageId, odeBlockId, blockName, iconName?, odePagStructureOrder, odePagStructureProperties?, odeComponents?)>
<!ELEMENT odeComponents (odeComponent*)>
<!ELEMENT odeComponent (odePageId, odeBlockId, odeIdeviceId, odeIdeviceTypeName, htmlView?, jsonProperties?, odeComponentsOrder, odeComponentsProperties?)>
```

The full structural reference is in [pages-blocks.md](pages-blocks.md). This section gives the element-by-element schema.

### `<odeNavStructure>` — a page

```xml
<odeNavStructure>
  <odePageId>20251217062007PAGE01</odePageId>
  <odeParentPageId/>                    <!-- empty = root level -->
  <pageName>Introduction</pageName>
  <odeNavStructureOrder>0</odeNavStructureOrder>
  <odeNavStructureProperties>...</odeNavStructureProperties>
  <odePagStructures>...</odePagStructures>
</odeNavStructure>
```

| Element | Cardinality | Type | Description |
|---------|-------------|------|-------------|
| `<odePageId>` | 1 | ODE identifier | Unique per page. See [ids.md](ids.md). |
| `<odeParentPageId>` | 1 | ODE identifier or empty | `<odeParentPageId/>` (empty) for root pages; otherwise the `odePageId` of the parent page. |
| `<pageName>` | 1 | string | Display name in navigation. Defaults to `"Page"` when missing. XML-escaped. |
| `<odeNavStructureOrder>` | 1 | integer | Sort key among siblings (0-based in modern generator). |
| `<odeNavStructureProperties>` | 0 or 1 | container | Page-level key/value properties. |
| `<odePagStructures>` | 0 or 1 | container | Blocks contained in the page. |

### `<odeNavStructureProperty>` — page-level property

`<key>` + `<value>` pair. The generator always emits `titlePage` ([`OdeXmlGenerator.ts:166`](../../src/shared/export/generators/OdeXmlGenerator.ts)) and may emit any extra keys that the editor stored on the page object.

| Key | Type | Description |
|-----|------|-------------|
| `titlePage` | string | Heading rendered above the page content (often equal to `<pageName>`). |
| `titleNode` | string | Navigation label override. |
| `titleHtml` | string (HTML) | Custom HTML title. |
| `hidePageTitle` | boolean | If `"true"`, suppress the rendered `<h1>`. |
| `editableInPage` | boolean | Allow inline page-title editing (editor only). |
| `visibility` | boolean | Hide the page in navigation when `"false"`. |
| `highlight` | boolean | Mark the page as highlighted in navigation. |
| `description` | string | Short description shown in tooltips and indices. |

### `<odePagStructure>` — a block (container of components)

```xml
<odePagStructure>
  <odePageId>20251217062007PAGE01</odePageId>      <!-- redundant but DTD-required -->
  <odeBlockId>20251217062007BLK001</odeBlockId>
  <blockName>Text</blockName>
  <iconName/>
  <odePagStructureOrder>0</odePagStructureOrder>
  <odePagStructureProperties>...</odePagStructureProperties>
  <odeComponents>...</odeComponents>
</odePagStructure>
```

| Element | Cardinality | Type | Description |
|---------|-------------|------|-------------|
| `<odePageId>` | 1 | ODE identifier | Echoes the enclosing page ID. **Must** match the parent `<odeNavStructure>`'s `<odePageId>`. |
| `<odeBlockId>` | 1 | ODE identifier | Unique per block. |
| `<blockName>` | 1 | string | Human label for the block. May be empty. |
| `<iconName>` | 0 or 1 | string | Optional theme icon name. The generator emits `<iconName/>` when absent. |
| `<odePagStructureOrder>` | 1 | integer | Sort key among sibling blocks (0-based). |
| `<odePagStructureProperties>` | 0 or 1 | container | Block-level properties. |
| `<odeComponents>` | 0 or 1 | container | iDevice components in this block. |

Block-level properties emitted by the generator ([`OdeXmlGenerator.ts:213`](../../src/shared/export/generators/OdeXmlGenerator.ts)):

| Key | Type | Description |
|-----|------|-------------|
| `visibility` | boolean | Whether the block is rendered. |
| `teacherOnly` | boolean | Restrict the block to teacher view. |
| `allowToggle` | boolean | Whether users can collapse/expand the block. |
| `minimized` | boolean | Whether the block starts collapsed. |
| `cssClass` | string | Extra CSS class(es) applied to the block container. |

The legacy property `identifier` (custom HTML `id`) is tolerated on import but no longer emitted.

### `<odeComponent>` — an iDevice instance

```xml
<odeComponent>
  <odePageId>20251217062007PAGE01</odePageId>     <!-- redundant; must match enclosing page -->
  <odeBlockId>20251217062007BLK001</odeBlockId>   <!-- redundant; must match enclosing block -->
  <odeIdeviceId>20251217062007IDEV1</odeIdeviceId>
  <odeIdeviceTypeName>text</odeIdeviceTypeName>
  <htmlView><![CDATA[<div class="exe-text-template">...</div>]]></htmlView>
  <jsonProperties><![CDATA[{"textTextarea":"...","ideviceId":"..."}]]></jsonProperties>
  <odeComponentsOrder>0</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty>
      <key>visibility</key>
      <value>true</value>
    </odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

| Element | Cardinality | Type | Description |
|---------|-------------|------|-------------|
| `<odePageId>` | 1 | ODE identifier | Echoes the enclosing page ID. Must match. |
| `<odeBlockId>` | 1 | ODE identifier | Echoes the enclosing block ID. Must match. |
| `<odeIdeviceId>` | 1 | ODE identifier | Unique per component. |
| `<odeIdeviceTypeName>` | 1 | string (enum) | iDevice type. See [idevices/catalog.md](idevices/catalog.md) for the full list. Legacy CamelCase names are accepted on import and remapped via [`IDEVICE_TYPE_MAP`](../../src/shared/export/constants.ts) at `constants.ts:843`. |
| `<htmlView>` | 0 or 1 | CDATA-wrapped HTML | Pre-rendered HTML for export. See [CDATA rules](#cdata-and-escaping-rules) below. |
| `<jsonProperties>` | 0 or 1 | CDATA-wrapped JSON | Editable state for re-import. See [idevices/patterns.md](idevices/patterns.md) for the four storage patterns. |
| `<odeComponentsOrder>` | 1 | integer | Sort key among siblings (0-based). |
| `<odeComponentsProperties>` | 0 or 1 | container | Component-level properties. |

Component-level properties emitted by the generator ([`OdeXmlGenerator.ts:285`](../../src/shared/export/generators/OdeXmlGenerator.ts)):

| Key | Type | Description |
|-----|------|-------------|
| `visibility` | boolean | Whether the component renders. Always emitted; defaults to `"true"`. |
| `teacherOnly` | boolean | Restrict to teacher view. |
| `cssClass` | string | Extra CSS class(es) applied to the component container. |

> **DTD requirement**: although `<odeComponentsProperties>` is marked optional in the DTD, the generator always emits it (with at least `visibility=true` when no other properties are present). When generating `.elpx` programmatically, emit an empty `<odeComponentsProperties></odeComponentsProperties>` rather than omitting the element — many third-party validators expect it.

---

## CDATA and escaping rules

### Rule 1 — `<htmlView>` and `<jsonProperties>` are ALWAYS CDATA-wrapped

Every emitted `<htmlView>` and `<jsonProperties>` element has its content wrapped in `<![CDATA[ ... ]]>` ([`OdeXmlGenerator.ts:270, 275`](../../src/shared/export/generators/OdeXmlGenerator.ts)). This applies even when the content does not contain any XML-significant characters. Examples:

```xml
<htmlView><![CDATA[<p>Hello world</p>]]></htmlView>
<jsonProperties><![CDATA[{"textTextarea":"<p>Hello world</p>","ideviceId":"20251217062007IDEV1"}]]></jsonProperties>
```

### Rule 2 — `]]>` inside CDATA must be split

CDATA cannot contain the literal sequence `]]>` because it terminates the section. The exporter handles this with [`escapeCdata` (`OdeXmlGenerator.ts:352`](../../src/shared/export/generators/OdeXmlGenerator.ts)):

```js
str.replace(/\]\]>/g, ']]]]><![CDATA[>');
```

When generating `.elpx` by hand or with an LLM, apply the same transform. A paragraph containing the literal text `the operator ]]>` becomes:

```xml
<htmlView><![CDATA[<p>the operator ]]]]><![CDATA[> is rare</p>]]></htmlView>
```

(That is two adjacent CDATA sections; XML parsers concatenate them transparently.)

### Rule 3 — XML attribute and text escaping elsewhere

For all other text nodes (page names, property values, block names, etc.), the generator uses [`escapeXml` (`OdeXmlGenerator.ts:337`](../../src/shared/export/generators/OdeXmlGenerator.ts)):

| Input character | Replaced with |
|-----------------|---------------|
| `&` | `&amp;` |
| `<` | `&lt;` |
| `>` | `&gt;` |
| `"` | `&quot;` |
| `'` | `&apos;` |

Empty / null / undefined values become an empty string.

### Rule 4 — UTF-8 throughout

No BOM, no UTF-16. Non-ASCII characters appear directly in their UTF-8 bytes. Numeric character references are not used.

---

## DTD (bundled inside every `.elpx`)

The DTD is bundled at the ZIP root as `content.dtd`. It is generated from the constant [`ODE_DTD_CONTENT` in `src/shared/export/constants.ts:1006`](../../src/shared/export/constants.ts):

```dtd
<!--
    ODE Content DTD
    Document Type Definition for eXeLearning ODE XML format (content.xml)
    Version: 2.0
    Namespace: http://www.intef.es/xsd/ode
    Copyright (C) 2025 eXeLearning - License: AGPL-3.0
-->

<!ELEMENT ode (userPreferences?, odeResources?, odeProperties?, odeNavStructures)>
<!ATTLIST ode
    xmlns CDATA #FIXED "http://www.intef.es/xsd/ode"
    version CDATA #IMPLIED>

<!-- User Preferences -->
<!ELEMENT userPreferences (userPreference*)>
<!ELEMENT userPreference (key, value)>

<!-- ODE Resources -->
<!ELEMENT odeResources (odeResource*)>
<!ELEMENT odeResource (key, value)>

<!-- ODE Properties -->
<!ELEMENT odeProperties (odeProperty*)>
<!ELEMENT odeProperty (key, value)>

<!-- Shared Key-Value Elements -->
<!ELEMENT key (#PCDATA)>
<!ELEMENT value (#PCDATA)>

<!-- Navigation Structures (Pages) -->
<!ELEMENT odeNavStructures (odeNavStructure*)>
<!ELEMENT odeNavStructure (odePageId, odeParentPageId, pageName, odeNavStructureOrder, odeNavStructureProperties?, odePagStructures?)>

<!ELEMENT odePageId (#PCDATA)>
<!ELEMENT odeParentPageId (#PCDATA)>
<!ELEMENT pageName (#PCDATA)>
<!ELEMENT odeNavStructureOrder (#PCDATA)>

<!ELEMENT odeNavStructureProperties (odeNavStructureProperty*)>
<!ELEMENT odeNavStructureProperty (key, value)>

<!-- Block Structures -->
<!ELEMENT odePagStructures (odePagStructure*)>
<!ELEMENT odePagStructure (odePageId, odeBlockId, blockName, iconName?, odePagStructureOrder, odePagStructureProperties?, odeComponents?)>

<!ELEMENT odeBlockId (#PCDATA)>
<!ELEMENT blockName (#PCDATA)>
<!ELEMENT iconName (#PCDATA)>
<!ELEMENT odePagStructureOrder (#PCDATA)>

<!ELEMENT odePagStructureProperties (odePagStructureProperty*)>
<!ELEMENT odePagStructureProperty (key, value)>

<!-- Components (iDevices) -->
<!ELEMENT odeComponents (odeComponent*)>
<!ELEMENT odeComponent (odePageId, odeBlockId, odeIdeviceId, odeIdeviceTypeName, htmlView?, jsonProperties?, odeComponentsOrder, odeComponentsProperties?)>

<!ELEMENT odeIdeviceId (#PCDATA)>
<!ELEMENT odeIdeviceTypeName (#PCDATA)>
<!ELEMENT htmlView (#PCDATA)>
<!ELEMENT jsonProperties (#PCDATA)>
<!ELEMENT odeComponentsOrder (#PCDATA)>

<!ELEMENT odeComponentsProperties (odeComponentsProperty*)>
<!ELEMENT odeComponentsProperty (key, value)>
```

A canonical, more heavily commented version of the same DTD lives in the repository at [`public/app/schemas/ode/content.dtd`](../../public/app/schemas/ode/content.dtd). The two are equivalent in element structure; only the comments differ.

---

## XSD (companion schema, not bundled)

A stricter XML Schema is available at [`public/app/schemas/ode/ode-content.xsd`](../../public/app/schemas/ode/ode-content.xsd). Use it when you need stronger validation than the DTD provides.

### What the XSD adds beyond the DTD

| Feature | XSD constraint | DTD equivalent |
|---------|----------------|----------------|
| Identifier format | `xs:pattern value="[0-9]{14}[A-Z0-9]{6}\|page-[a-z0-9-]+\|[a-zA-Z0-9_-]+"` on `odeIdentifierType` | None — `#PCDATA` |
| iDevice type list | `xs:enumeration` of every modern + legacy/FPD type name (`ideviceTypeType`) | None — `#PCDATA` |
| Property key list | `xs:enumeration` of recognized `pp_*` keys (`propertyKeyType`) | None — `#PCDATA` |
| Boolean strings | `xs:enumeration` `"true"`, `"false"`, `"True"`, `"False"` (`booleanStringType`) | None |
| Order numbers | `xs:integer` for `*Order` elements | `#PCDATA` |
| Required `odeNavStructure` | `minOccurs="1"` | None — DTD allows zero |

The XSD is intentionally not bundled inside `.elpx` because (a) DTDs are still the de-facto standard that many lightweight validators understand, and (b) keeping the bundled schema small saves bytes.

### Validating with the XSD

```bash
xmllint --noout --schema public/app/schemas/ode/ode-content.xsd path/to/content.xml
```

See [validation.md](validation.md) for the full validation playbook.

---

## Cardinality and ordering summary

A compact reference for code generators:

```
ode
├── userPreferences?         (0..1)
│     └── userPreference*
│            ├── key
│            └── value
├── odeResources?            (0..1)
│     └── odeResource*
│            ├── key
│            └── value
├── odeProperties?           (0..1)
│     └── odeProperty*
│            ├── key
│            └── value
└── odeNavStructures         (1..1)   <-- the only required top-level child
      └── odeNavStructure*
             ├── odePageId            (1)
             ├── odeParentPageId      (1)        <!-- empty for root pages -->
             ├── pageName             (1)
             ├── odeNavStructureOrder (1)
             ├── odeNavStructureProperties?
             │     └── odeNavStructureProperty*
             │            ├── key
             │            └── value
             └── odePagStructures?
                   └── odePagStructure*
                          ├── odePageId             (1)        <!-- redundant -->
                          ├── odeBlockId            (1)
                          ├── blockName             (1)
                          ├── iconName?             (0..1)
                          ├── odePagStructureOrder  (1)
                          ├── odePagStructureProperties?
                          │     └── odePagStructureProperty*
                          │            ├── key
                          │            └── value
                          └── odeComponents?
                                └── odeComponent*
                                       ├── odePageId             (1)
                                       ├── odeBlockId            (1)
                                       ├── odeIdeviceId          (1)
                                       ├── odeIdeviceTypeName    (1)
                                       ├── htmlView?             (0..1)  CDATA-wrapped
                                       ├── jsonProperties?       (0..1)  CDATA-wrapped
                                       ├── odeComponentsOrder    (1)
                                       └── odeComponentsProperties?
                                             └── odeComponentsProperty*
                                                    ├── key
                                                    └── value
```

Element order is **strict**: a parser MUST reject an `<odeComponent>` whose `<htmlView>` appears after its `<odeComponentsOrder>`, or an `<odeNavStructure>` that places `<pageName>` before `<odeParentPageId>`.

---

## Common gotchas

1. **Redundant IDs must be in lockstep.** `<odePageId>` and `<odeBlockId>` appear at every nesting level (page, block, component). All three references inside an `<odeComponent>` MUST agree with the IDs of the enclosing `<odePagStructure>` and `<odeNavStructure>`. Mismatches make the importer reject the component or attach it to the wrong block.
2. **Boolean strings only.** Properties typed as boolean in [`metadata-properties.ts`](../../src/shared/export/metadata-properties.ts) are emitted as the literal strings `"true"` / `"false"`. Do not use `1`/`0`, `True`/`False`, or `yes`/`no`. The XSD `booleanStringType` is permissive on capitalization, but the importer's `parsePropertyValue` (`metadata-properties.ts:333`) only checks `toLowerCase() === 'true'`.
3. **Always emit `<odeComponentsProperties>` even when empty.** The DTD marks it optional, but every reference fixture and the generator always emit it (with at least `visibility=true`). Some third-party tools assume its presence.
4. **CDATA wrappers are unconditional** for `<htmlView>` and `<jsonProperties>`. Do not "optimize" by emitting raw HTML-escaped content — the importer's regex-based extractors expect CDATA delimiters.
5. **Page hierarchy is flat in XML.** Nesting one `<odeNavStructure>` inside another's `<odePagStructures>` is invalid. Use `<odeParentPageId>` to express parent-child relationships.
6. **`exe_version`, not `eXeVersion`.** The XML key for the runtime version is `exe_version` (snake_case). The misspelling `eXeVersion` appears in some old fixtures; the importer accepts both, but the modern generator only writes `exe_version`.
7. **Asset references use `{{context_path}}`.** Inside `<htmlView>` and `<jsonProperties>`, asset URLs take the v4 form `{{context_path}}/<exportPath>` where `<exportPath>` is `<folderPath>/<filename>` for assets inside a user-created folder (e.g. `photos/vacation/sunset.jpg`) or just `<filename>` when no folder. The placeholder absorbs both the page-depth `../` prefix and the `content/resources/` segment. The legacy long form `{{context_path}}/content/resources/<exportPath>` is also accepted on import. The asset itself lives at `content/resources/<exportPath>` inside the ZIP — never inside a legacy v3 per-asset UUID subfolder (`[0-9]{14}[A-Z0-9]{6}`). The import pipeline rewrites either reference form to `asset://<uuid>`. See [assets.md](assets.md).

---

## See also

- [container.md](container.md) — every file inside an `.elpx` ZIP
- [ids.md](ids.md) — ODE identifier format, lifecycle, and synchronization rules
- [metadata.md](metadata.md) — full reference for `pp_*` keys, `userPreferences`, `odeResources`
- [pages-blocks.md](pages-blocks.md) — flat-list navigation model, internal `exe-node:` links
- [idevices/catalog.md](idevices/catalog.md) — every iDevice type
- [idevices/patterns.md](idevices/patterns.md) — the four content-storage patterns
- [validation.md](validation.md) — validating with `xmllint` and `OdeXmlValidator`
- [ai-generation.md](ai-generation.md) — rules for LLMs producing `.elpx`
- [examples/minimal-content-xml.md](examples/minimal-content-xml.md) — a complete, validating example


# ===== doc/elpx-format/ids.md =====

# ELPX Identifiers

This document describes every identifier used in a `content.xml` file: their format, generation, lifecycle, synchronization rules, and what happens to them during import.

See also: [ELPX format overview](../elpx-format.md) | [Container](container.md) | [Pages and blocks](pages-blocks.md) | [Metadata](metadata.md)

---

## ID format

Modern ODE identifiers are produced by `generateOdeId()` in `OdeXmlGenerator.ts:315–332`:

```
YYYYMMDDHHmmss  +  6 chars from [A-Z0-9]
```

**Example:** `20251125215856KTWCLS`

- Characters 1–14: UTC wall-clock timestamp, zero-padded (`YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`).
- Characters 15–20: six characters drawn uniformly at random from the 36-character alphabet `ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789`.

This gives the ID two useful properties: it is lexicographically time-sortable (earlier IDs sort before later ones), and the 6-character random suffix makes collisions extremely unlikely even when many IDs are generated within the same second.

```typescript
// OdeXmlGenerator.ts:315–332
export function generateOdeId(): string {
    const now = new Date();
    const timestamp =
        now.getFullYear().toString() +
        String(now.getMonth() + 1).padStart(2, '0') +
        String(now.getDate()).padStart(2, '0') +
        String(now.getHours()).padStart(2, '0') +
        String(now.getMinutes()).padStart(2, '0') +
        String(now.getSeconds()).padStart(2, '0');

    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
    let random = '';
    for (let i = 0; i < 6; i++) {
        random += chars.charAt(Math.floor(Math.random() * chars.length));
    }
    return timestamp + random;
}
```

---

## XSD `odeIdentifierType` pattern

The XML Schema (`ode-content.xsd:148–152`) defines a union pattern for all ID attributes:

```
[0-9]{14}[A-Z0-9]{6}|page-[a-z0-9-]+|[a-zA-Z0-9_-]+
```

The three alternations exist for distinct historical reasons:

| Alternation | Example | Reason |
|---|---|---|
| `[0-9]{14}[A-Z0-9]{6}` | `20251125215856KTWCLS` | Modern format produced by `generateOdeId()`. |
| `page-[a-z0-9-]+` | `page-introduction` | Slug-style IDs used in older eXeLearning 3.x imports where page IDs were derived from page titles. |
| `[a-zA-Z0-9_-]+` | `idevice-3` or `page-4` | Generic legacy IDs from Python eXeLearning 2.x (`.elp` files) where pages and iDevices had small sequential integers as identifiers. |

All three forms are accepted by the importer. The modern generator always produces the first form.

---

## Identifier lifecycle

| Identifier | Set when | Changes when | Notes |
|---|---|---|---|
| `odeId` | Project is created for the first time | Never (stable for the project's lifetime) | Stored in `odeResources`. Retrieved from `meta.odeIdentifier` if already set, otherwise `generateOdeId()` is called once (`OdeXmlGenerator.ts:44`). |
| `odeVersionId` | Every export / save | Every export / save | Always a freshly generated `generateOdeId()` call (`OdeXmlGenerator.ts:45`). Acts as a change cursor. |
| `odePageId` | Page is created | On import (reassigned — see below) | Stable within a project; changes only when the file is re-imported. |
| `odeBlockId` | Block is created | On import (reassigned) | Stable within a project; changes only when the file is re-imported. |
| `odeIdeviceId` | iDevice is added | On import (reassigned) | Stable within a project; changes only when the file is re-imported. |

---

## Synchronization: redundant IDs inside blocks and components

The DTD (`content.dtd:69`) requires `<odePageId>` as the first child of every `<odePagStructure>` (block), and again as the first child of every `<odeComponent>`. These are not independent IDs — they must equal the `<odePageId>` of the enclosing `<odeNavStructure>`.

The generator enforces this in lockstep:

```typescript
// OdeXmlGenerator.ts:203–205 (block generation)
xml += `    <odePagStructure>\n`;
xml += `      <odePageId>${escapeXml(pageId)}</odePageId>\n`;   // pageId passed from parent
xml += `      <odeBlockId>${escapeXml(blockId)}</odeBlockId>\n`;

// OdeXmlGenerator.ts:262–265 (component generation)
xml += `        <odeComponent>\n`;
xml += `          <odePageId>${escapeXml(pageId)}</odePageId>\n`;   // same pageId, passed down
xml += `          <odeBlockId>${escapeXml(blockId)}</odeBlockId>\n`; // blockId from enclosing block
xml += `          <odeIdeviceId>${escapeXml(componentId)}</odeIdeviceId>\n`;
```

In other words: `pageId` is threaded through from `generateOdeNavStructureXml()` → `generateOdePagStructureXml()` → `generateOdeComponentXml()` as a function argument, so the emitted values are always in lockstep with the enclosing structure.

A parser that encounters a mismatch between the block's `<odePageId>` and its parent `<odeNavStructure>`'s `<odePageId>` should treat the outer (navigation-level) value as authoritative.

---

## ID collision handling on import

Every time an `.elpx` or `.elp` file is imported, **all page IDs are regenerated**. This happens unconditionally, even when `clearExisting: true` replaces the entire Y.Doc.

### Modern format (`.elpx`)

`buildFlatPageList()` (`ElpxImporter.ts:955`) calls `this.generateId('page')` for every `<odeNavStructure>` it encounters, mapping the original XML ID to the new one via an `idRemap: Map<string, string>`. Block IDs and iDevice IDs are similarly regenerated inside `buildPageData()`.

The importer's `generateId()` (`ElpxImporter.ts:1824`) uses a different format from the exporter's `generateOdeId()`:

```
<prefix>-<Date.now().toString(36)>-<Math.random().toString(36).substring(2,11)>
```

Examples: `page-m4x1z2-ab3cd4ef5`, `block-m4x1z3-xyz987`.

This format matches the `page-[a-z0-9-]+` and `[a-zA-Z0-9_-]+` alternations in the XSD identifier pattern, and it is always globally unique within a session because `Date.now()` advances between calls.

### Legacy format (`.elp`)

`convertLegacyPagesToPageData()` (`ElpxImporter.ts:644–688`) builds a full `pageIdRemap` map before processing any page, so that parent-child relationships (which reference old IDs) can be resolved consistently using the new IDs.

The rationale for always remapping (even on full replacement) is stated in a comment at `ElpxImporter.ts:653`:

> "Legacy IDs are stable inside .elp files (e.g. page-4, idevice-2). On repeated imports into the same Y.Doc we must remap to unique IDs to avoid collisions."

This applies equally to modern ELPX imports: importing the same `.elpx` twice into one Y.Doc must produce distinct page IDs.

### Internal link repair

After all IDs are remapped, `remapInternalPageLinks()` (`ElpxImporter.ts:1453–1479`) walks every component's `htmlView` and `properties` (recursively) and rewrites `exe-node:<oldId>` references to `exe-node:<newId>`. Both the HTML attribute value and the JSON stored in `jsonProperties` are updated — for example, a `text` iDevice stores its content in `jsonProperties.textTextarea`, not only in `htmlView`, so both locations must be patched.

The rewrite uses a single compiled regex that matches all old IDs in one pass, preserving any `#fragment` suffix:

```
href="exe-node:oldId"           → href="exe-node:newId"
href="exe-node:oldId#section1"  → href="exe-node:newId#section1"
```

---

## Annotated example: IDs in a two-page export

```xml
<odeResources>
  <odeResource>
    <key>odeId</key>
    <!-- Stable project identifier, never regenerated after first creation -->
    <value>20251125215855LURLBW</value>
  </odeResource>
  <odeResource>
    <key>odeVersionId</key>
    <!-- Regenerated on every export/save -->
    <value>20251125220103ABCXYZ</value>
  </odeResource>
  <odeResource>
    <key>exe_version</key>
    <value>3.0</value>
  </odeResource>
</odeResources>

<odeNavStructures>
  <odeNavStructure>
    <odePageId>20251125215855PAGE01</odePageId>   <!-- page ID -->
    <odeParentPageId/>                            <!-- root: no parent -->
    ...
    <odePagStructures>
      <odePagStructure>
        <odePageId>20251125215855PAGE01</odePageId> <!-- must match enclosing page -->
        <odeBlockId>20251125215855BLK001</odeBlockId>
        ...
        <odeComponents>
          <odeComponent>
            <odePageId>20251125215855PAGE01</odePageId>  <!-- must match enclosing page -->
            <odeBlockId>20251125215855BLK001</odeBlockId> <!-- must match enclosing block -->
            <odeIdeviceId>20251125215855IDEV01</odeIdeviceId>
            ...
          </odeComponent>
        </odeComponents>
      </odePagStructure>
    </odePagStructures>
  </odeNavStructure>

  <odeNavStructure>
    <odePageId>20251125215855PAGE02</odePageId>
    <!-- child of PAGE01: href="exe-node:PAGE01" would link back to parent -->
    <odeParentPageId>20251125215855PAGE01</odeParentPageId>
    ...
  </odeNavStructure>
</odeNavStructures>
```


# ===== doc/elpx-format/metadata.md =====

# ELPX Metadata

This document describes the three top-level metadata containers in `content.xml` (`<userPreferences>`, `<odeResources>`, `<odeProperties>`), every property key they carry, serialization rules, and round-trip behaviour through the importer.

See also: [ELPX format overview](../elpx-format.md) | [Container](container.md) | [IDs](ids.md) | [Pages and blocks](pages-blocks.md)

---

## Overview

The `<ode>` root element contains three metadata containers before `<odeNavStructures>`. All three are optional in the DTD (`content.dtd:20`) but are always emitted by `OdeXmlGenerator`:

```xml
<ode xmlns="http://www.intef.es/xsd/ode" version="2.0">
  <userPreferences> ... </userPreferences>
  <odeResources>    ... </odeResources>
  <odeProperties>   ... </odeProperties>
  <odeNavStructures> ... </odeNavStructures>
</ode>
```

---

## 1. `<userPreferences>`

Stores user-level configuration. Every entry is a `<userPreference>` with a `<key>` and `<value>` child.

The generator (`OdeXmlGenerator.ts:77–82`) emits exactly one entry:

```typescript
function generateUserPreferencesXml(meta: ExportMetadata): string {
    let xml = '<userPreferences>\n';
    xml += generateUserPreferenceEntry('theme', meta.theme || 'base');
    xml += '</userPreferences>\n';
    return xml;
}
```

| Key | Default | Description |
|---|---|---|
| `theme` | `'base'` | Active theme name. Matches the theme directory bundled in `theme/` inside the ZIP. |

No other keys are currently written to `<userPreferences>` by the generator. Additional keys may appear in files produced by older versions and should be preserved on round-trip.

```xml
<userPreferences>
  <userPreference>
    <key>theme</key>
    <value>base</value>
  </userPreference>
</userPreferences>
```

---

## 2. `<odeResources>`

Stores package-level identifiers and the generator version. Every entry is an `<odeResource>` with a `<key>` and `<value>` child.

The generator (`OdeXmlGenerator.ts:97–103`) emits exactly three entries:

```typescript
function generateOdeResourcesXml(odeId: string, versionId: string): string {
    let xml = '<odeResources>\n';
    xml += generateOdeResourceEntry('odeId', odeId);
    xml += generateOdeResourceEntry('odeVersionId', versionId);
    xml += generateOdeResourceEntry('exe_version', ODE_VERSION);
    xml += '</odeResources>\n';
    return xml;
}
```

`ODE_VERSION` is the constant `'3.0'` defined in `constants.ts:1000`.

| Key | Description |
|---|---|
| `odeId` | Stable project identifier. Retrieved from `meta.odeIdentifier` on export; generated once via `generateOdeId()` if absent. |
| `odeVersionId` | Regenerated on every export/save via `generateOdeId()`. Acts as a change cursor. |
| `exe_version` | The ODE format version string, currently `'3.0'` (constant `ODE_VERSION` from `constants.ts:1000`). |

**Legacy keys observed in older fixtures:** the v4 generator writes exactly three resources (`odeId`, `odeVersionId`, `exe_version`). Some older fixtures additionally carry `odeVersionName`, `isDownload`, or the misspelling `eXeVersion`. The importer accepts all of these for backward compatibility, but **`generateOdeResourcesXml()` never emits them in v4** — treat them as informational legacy keys when reading older `.elpx` files.

```xml
<odeResources>
  <odeResource>
    <key>odeId</key>
    <value>20251125215855LURLBW</value>
  </odeResource>
  <odeResource>
    <key>odeVersionId</key>
    <value>20251125220103ABCXYZ</value>
  </odeResource>
  <odeResource>
    <key>exe_version</key>
    <value>3.0</value>
  </odeResource>
</odeResources>
```

---

## 3. `<odeProperties>`

Stores document metadata. Every entry is an `<odeProperty>` with a `<key>` and `<value>` child. The generator iterates `Object.entries(meta)` and emits one entry per property that is not excluded, not empty, and not null/undefined (`OdeXmlGenerator.ts:121–138`).

The single source of truth for every property is `METADATA_PROPERTIES` in `metadata-properties.ts`.

### Full property table

| Internal key | XML key | Type | Default | Category | Description |
|---|---|---|---|---|---|
| `title` | `pp_title` | string | `'eXeLearning'` | core | Project title |
| `subtitle` | `pp_subtitle` | string | `''` | core | Project subtitle |
| `author` | `pp_author` | string | `''` | core | Author name |
| `description` | `pp_description` | string | `''` | core | Project description |
| `language` | `pp_lang` | string | `'en'` | core | Language code (BCP 47, e.g. `'en'`, `'es'`) |
| `license` | `pp_license` | string | `''` | core | License identifier (e.g. `'creative commons: attribution - share alike 4.0'`) |
| `licenseUrl` | `pp_licenseUrl` | string | `''` | core | License URL |
| `keywords` | `pp_keywords` | string | `''` | core | Comma-separated keywords |
| `category` | `pp_category` | string | `''` | core | Content category |
| `theme` | `pp_theme` | string | `'base'` | core | Theme name (also written to `<userPreferences>`) |
| `customStyles` | `pp_customStyles` | string | `''` | core | Custom CSS injected into all pages |
| `exelearningVersion` | `pp_exelearning_version` | string | `''` | core | eXeLearning application version string |
| `addExeLink` | `pp_addExeLink` | boolean | `true` | export | Include "Made with eXeLearning" footer link |
| `addPagination` | `pp_addPagination` | boolean | `false` | export | Add page navigation arrows |
| `addSearchBox` | `pp_addSearchBox` | boolean | `false` | export | Include search box |
| `addAccessibilityToolbar` | `pp_addAccessibilityToolbar` | boolean | `false` | export | Include accessibility toolbar |
| `addMathJax` | `pp_addMathJax` | boolean | `false` | export | Load MathJax for LaTeX rendering |
| `exportSource` | `exportSource` | boolean | `true` | export | Include editable source in export (no `pp_` prefix — legacy compatibility) |
| `globalFont` | `pp_globalFont` | string | `'default'` | export | Global font override |
| `extraHeadContent` | `pp_extraHeadContent` | string | `''` | content | Custom HTML injected into `<head>` of all pages |
| `footer` | `footer` | string | `''` | content | Custom footer HTML (no `pp_` prefix — legacy compatibility) |

Properties with `excludeFromXml: true` are **not** emitted to `<odeProperties>`:

| Internal key | Reason excluded |
|---|---|
| `odeIdentifier` | Written to `<odeResources>` as `odeId`; stored internally in Yjs but not in the property section. |
| `createdAt` | Internal timestamp; not persisted to XML. |
| `modifiedAt` | Internal timestamp; not persisted to XML. |
| `scormIdentifier` | Goes into the SCORM manifest (`imsmanifest.xml`), not `content.xml`. |
| `masteryScore` | Goes into the SCORM manifest, not `content.xml`. |

---

## Boolean serialization

Booleans are stored as the literal strings `"true"` or `"false"`. The `valueToXmlString()` function (`metadata-properties.ts:354–360`) handles this:

```typescript
export function valueToXmlString(key: string, value: unknown): string {
    const config = getPropertyConfig(key);
    if (config?.type === 'boolean') {
        return value === true || value === 'true' ? 'true' : 'false';
    }
    return String(value ?? '');
}
```

The XSD (`ode-content.xsd:242–249`) defines a `booleanStringType` that accepts `"true"`, `"false"`, `"True"`, and `"False"`. On import, the parser normalises these via `value.toLowerCase() === 'true'`.

---

## Round-trip: XML key to internal key mapping

On import, `xml-parser.ts` reads each `<odeProperty>` and maps its `<key>` text back to the internal property name using `getInternalKeyForXmlKey()` (`metadata-properties.ts:287–290`):

```typescript
export function getInternalKeyForXmlKey(xmlKey: string): string | undefined {
    const config = getPropertyConfigByXmlKey(xmlKey);
    return config?.key;
}
```

`getPropertyConfigByXmlKey()` performs a **case-insensitive** lookup by lowercasing both the candidate key and the stored `xmlKey` values:

```typescript
export function getPropertyConfigByXmlKey(xmlKey: string): MetadataPropertyConfig | undefined {
    const lowerXmlKey = xmlKey.toLowerCase();
    return METADATA_PROPERTIES.find(p => p.xmlKey.toLowerCase() === lowerXmlKey);
}
```

This means `pp_Title`, `PP_TITLE`, and `pp_title` all resolve to the internal key `title`. Keys not found in `METADATA_PROPERTIES` are currently dropped by the parser (no fallback passthrough for unknown keys).

---

## Legacy `.elp` files

Legacy `.elp` files use Python pickle XML (`contentv3.xml`), not ODE 2.0. Metadata is stored as a `<dictionary>` of Python object fields, not `<odeProperty>` entries. The `LegacyXmlParser.ts` handles this format. For full details see [Legacy ELP Format (contentv3.xml)](../contentv3-format.md).

---

## Annotated example: all three sections fully populated

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ode SYSTEM "content.dtd">
<ode xmlns="http://www.intef.es/xsd/ode" version="2.0">

  <!-- Section 1: user-level configuration -->
  <userPreferences>
    <userPreference>
      <key>theme</key>
      <value>base</value>        <!-- only key emitted by modern generator -->
    </userPreference>
  </userPreferences>

  <!-- Section 2: package-level identifiers -->
  <odeResources>
    <odeResource>
      <key>odeId</key>
      <value>20260427090000PROJID</value>    <!-- stable; never regenerated -->
    </odeResource>
    <odeResource>
      <key>odeVersionId</key>
      <value>20260427091500VERSID</value>    <!-- new on every export -->
    </odeResource>
    <odeResource>
      <key>exe_version</key>
      <value>3.0</value>                    <!-- ODE_VERSION constant -->
    </odeResource>
  </odeResources>

  <!-- Section 3: document metadata -->
  <odeProperties>
    <!-- Core metadata -->
    <odeProperty><key>pp_title</key><value>Introduction to Biology</value></odeProperty>
    <odeProperty><key>pp_subtitle</key><value>Unit 1</value></odeProperty>
    <odeProperty><key>pp_author</key><value>Jane Doe</value></odeProperty>
    <odeProperty><key>pp_description</key><value>First-year biology overview.</value></odeProperty>
    <odeProperty><key>pp_lang</key><value>en</value></odeProperty>
    <odeProperty><key>pp_license</key><value>creative commons: attribution - share alike 4.0</value></odeProperty>
    <odeProperty><key>pp_licenseUrl</key><value>https://creativecommons.org/licenses/by-sa/4.0/</value></odeProperty>
    <odeProperty><key>pp_keywords</key><value>biology, cells, ecology</value></odeProperty>
    <odeProperty><key>pp_category</key><value>Science</value></odeProperty>
    <odeProperty><key>pp_theme</key><value>base</value></odeProperty>
    <odeProperty><key>pp_exelearning_version</key><value>4.0.0</value></odeProperty>

    <!-- Export options: booleans serialized as "true"/"false" strings -->
    <odeProperty><key>pp_addExeLink</key><value>true</value></odeProperty>
    <odeProperty><key>pp_addPagination</key><value>false</value></odeProperty>
    <odeProperty><key>pp_addSearchBox</key><value>true</value></odeProperty>
    <odeProperty><key>pp_addAccessibilityToolbar</key><value>true</value></odeProperty>
    <odeProperty><key>pp_addMathJax</key><value>false</value></odeProperty>
    <!-- exportSource has no pp_ prefix (legacy compatibility) -->
    <odeProperty><key>exportSource</key><value>true</value></odeProperty>
    <odeProperty><key>pp_globalFont</key><value>default</value></odeProperty>

    <!-- Custom content: HTML-escaped (stored in XML text nodes) -->
    <odeProperty>
      <key>pp_extraHeadContent</key>
      <value>&lt;meta name="robots" content="index,follow"&gt;</value>
    </odeProperty>
    <!-- footer has no pp_ prefix (legacy compatibility) -->
    <odeProperty>
      <key>footer</key>
      <value>&lt;p&gt;© 2026 Jane Doe&lt;/p&gt;</value>
    </odeProperty>
  </odeProperties>

  <!-- Excluded from odeProperties (not emitted):          -->
  <!--   odeIdentifier → odeResources/odeId                -->
  <!--   createdAt, modifiedAt → internal Yjs only         -->
  <!--   scormIdentifier, masteryScore → SCORM manifest    -->

  <odeNavStructures>
    <!-- ... pages ... -->
  </odeNavStructures>
</ode>
```


# ===== doc/elpx-format/pages-blocks.md =====

# ELPX Pages and Blocks

This document describes the page/block/component hierarchy stored in `<odeNavStructures>`, the flat-list page model, block composition, the properties emitted at each level, and internal page links.

See also: [ELPX format overview](../elpx-format.md) | [Container](container.md) | [IDs](ids.md) | [Metadata](metadata.md)

---

## Flat-list page model

Pages are **not** nested in XML. Every `<odeNavStructure>` is a sibling inside `<odeNavStructures>`, regardless of its depth in the content tree. The tree structure is expressed entirely through `<odeParentPageId>`:

- Empty `<odeParentPageId/>` (or absent) — root-level page.
- A non-empty `<odeParentPageId>` — child of the page with that ID.

A consumer reconstructs the tree by building a parent-lookup map over all `<odeNavStructure>` elements and then sorting each sibling group by `<odeNavStructureOrder>`.

Example from the fix-simple fixture (`content.xml`):

```
Page 1       (odePageId=20251217062007DGJTXL, parent="", order=1)
  Page 1-1   (odePageId=20251217062007TAOLOT, parent=DGJTXL,  order=1)
    Page 1-1-1 (odePageId=20251217062007OYUHOO, parent=TAOLOT, order=1)
  Page 1-2   (odePageId=20251217062007PYMEIX, parent=DGJTXL,  order=2)
Page 2       (odePageId=20251217062007XIMGJI, parent="",      order=2)
  Page 2-1   (odePageId=20251217062007SGKHYG, parent=XIMGJI,  order=1)
```

All six `<odeNavStructure>` elements appear at the same XML depth.

---

## Sibling ordering

`<odeNavStructureOrder>` is an integer. The generator (`OdeXmlGenerator.ts:162`) writes:

```typescript
xml += `  <odeNavStructureOrder>${page.order ?? order}</odeNavStructureOrder>\n`;
```

where `order` is the loop index (0-based) used as a fallback when `page.order` is not set. Sibling pages share the same parent and are ordered contiguously starting at 1 in the fixture (or 0 in the generator's fallback). Pages with identical order values among siblings are undefined behaviour — always emit distinct, contiguous integers.

---

## Page-level element reference

| Element | Required (DTD) | Type | Description | Source |
|---|---|---|---|---|
| `<odePageId>` | Yes | `odeIdentifierType` | Unique page identifier | `OdeXmlGenerator.ts:159` |
| `<odeParentPageId>` | Yes | string (may be empty) | Parent page ID; empty string = root | `OdeXmlGenerator.ts:160` |
| `<pageName>` | Yes | string | Page title used in navigation | `OdeXmlGenerator.ts:161` |
| `<odeNavStructureOrder>` | Yes | integer | Sort order among siblings | `OdeXmlGenerator.ts:162` |
| `<odeNavStructureProperties>` | No | property list | Page-level key/value properties | `OdeXmlGenerator.ts:165–174` |
| `<odePagStructures>` | No | block list | Blocks contained in this page | `OdeXmlGenerator.ts:176–181` |

### Page-level properties (`<odeNavStructureProperty>`)

The generator always emits `titlePage` (`OdeXmlGenerator.ts:166`), then any additional entries in `page.properties`:

| Key | Type | Description |
|---|---|---|
| `titlePage` | string | Always emitted; the rendered page heading |
| `titleNode` | string | Navigation label (may differ from `pageName`) |
| `titleHtml` | string (HTML) | Custom HTML title override |
| `hidePageTitle` | boolean string | Hide the page `<h1>` heading |
| `editableInPage` | boolean string | Allow inline title editing |
| `visibility` | boolean string | Whether the page is visible in navigation |
| `highlight` | boolean string | Highlight this page in the navigation |
| `description` | string | Short description shown in navigation |

The `titlePage` property is always present because it is emitted unconditionally by the generator. All other keys appear only when `page.properties` contains them.

---

## Block model

Each page contains zero or more blocks (`<odePagStructure>` elements) inside `<odePagStructures>`. A block is a layout container that holds one or more iDevice components.

The block repeats the enclosing page's ID as its first child (`<odePageId>`). This is required by the DTD (`content.dtd:69`) and must equal the ID in the parent `<odeNavStructure>`.

### Block-level element reference

| Element | Required (DTD) | Type | Description | Source |
|---|---|---|---|---|
| `<odePageId>` | Yes | `odeIdentifierType` | ID of the containing page (redundant — must match parent) | `OdeXmlGenerator.ts:204` |
| `<odeBlockId>` | Yes | `odeIdentifierType` | Unique block identifier | `OdeXmlGenerator.ts:205` |
| `<blockName>` | Yes | string | Human-readable block label | `OdeXmlGenerator.ts:206` |
| `<iconName>` | No | string | Icon identifier for the block (may be empty) | `OdeXmlGenerator.ts:207` |
| `<odePagStructureOrder>` | Yes | integer | Sort order within the page | `OdeXmlGenerator.ts:208` |
| `<odePagStructureProperties>` | No | property list | Block-level properties | `OdeXmlGenerator.ts:211–220` |
| `<odeComponents>` | No | component list | iDevice components | `OdeXmlGenerator.ts:223–228` |

### Block-level properties (`<odePagStructureProperty>`)

The generator iterates a fixed key list (`OdeXmlGenerator.ts:213`) and emits only the keys that are present in `block.properties`:

| Key | Type | Description |
|---|---|---|
| `visibility` | boolean string | Whether the block is visible |
| `teacherOnly` | boolean string | Restrict block to teacher view |
| `allowToggle` | boolean string | Allow block to be collapsed/expanded |
| `minimized` | boolean string | Block starts in collapsed state |
| `cssClass` | string | Optional extra CSS class(es) |

The `identifier` key (`cssClass` sibling) is written by older exporters and appears in real content.xml files (see fix-simple fixture), but is not in the generator's fixed key list — it will be present when passed via `block.properties` directly.

---

## Component model

Each block contains zero or more `<odeComponent>` elements inside `<odeComponents>`. A component represents one iDevice instance.

Like the block, the component repeats both the page ID and the block ID as its first two children. These must match the enclosing block's values.

### Component-level element reference

| Element | Required (DTD) | Type | Description | Source |
|---|---|---|---|---|
| `<odePageId>` | Yes | `odeIdentifierType` | Enclosing page ID (must match parent block's `<odePageId>`) | `OdeXmlGenerator.ts:263` |
| `<odeBlockId>` | Yes | `odeIdentifierType` | Enclosing block ID (must match parent `<odeBlockId>`) | `OdeXmlGenerator.ts:264` |
| `<odeIdeviceId>` | Yes | `odeIdentifierType` | Unique iDevice identifier | `OdeXmlGenerator.ts:265` |
| `<odeIdeviceTypeName>` | Yes | `ideviceTypeType` (XSD enum) | iDevice type string | `OdeXmlGenerator.ts:266` |
| `<htmlView>` | No | CDATA string | Pre-rendered HTML content | `OdeXmlGenerator.ts:270` |
| `<jsonProperties>` | No | CDATA string | iDevice configuration as JSON | `OdeXmlGenerator.ts:273–278` |
| `<odeComponentsOrder>` | Yes | integer | Sort order within the block | `OdeXmlGenerator.ts:280` |
| `<odeComponentsProperties>` | No | property list | Component-level structure properties | `OdeXmlGenerator.ts:283–295` |

### CDATA wrapping

`OdeXmlGenerator` **always** wraps `<htmlView>` and `<jsonProperties>` content in `<![CDATA[ ... ]]>` sections (`OdeXmlGenerator.ts:270`, `OdeXmlGenerator.ts:275`):

```typescript
xml += `          <htmlView><![CDATA[${escapeCdata(htmlContent)}]]></htmlView>\n`;
// ...
xml += `          <jsonProperties><![CDATA[${escapeCdata(jsonStr)}]]></jsonProperties>\n`;
```

The `escapeCdata()` function (`OdeXmlGenerator.ts:352–356`) handles the only forbidden sequence inside a CDATA section (`]]>`) by splitting it into adjacent CDATA sections:

```typescript
return String(str).replace(/\]\]>/g, ']]]]><![CDATA[>');
```

Note: the `content.xml` produced by older eXeLearning versions (pre-v3.0 or certain builds) uses HTML-entity escaping (`&lt;`, `&gt;`) instead of CDATA for these fields — see the fix-simple fixture as evidence. The importer handles both encodings because XML parsers decode both transparently. The existing overview in `doc/elpx-format.md` incorrectly stated that CDATA is not used; the modern generator always uses it.

### Component-level properties (`<odeComponentsProperty>`)

The generator iterates a fixed key list (`OdeXmlGenerator.ts:285`) and emits only the keys present in `component.structureProperties`. When `structureProperties` is absent, `visibility: true` is emitted as a default (`OdeXmlGenerator.ts:293`):

| Key | Type | Description |
|---|---|---|
| `visibility` | boolean string | Whether the iDevice is visible |
| `teacherOnly` | boolean string | Restrict iDevice to teacher view |
| `cssClass` | string | Optional extra CSS class(es) |

---

## Internal page links

Links between pages within the same project use the `exe-node:` URI scheme:

```html
<a href="exe-node:20251125215855PAGE02">Section 2</a>
<a href="exe-node:20251125215855PAGE02#introduction">Section 2 intro</a>
```

These URIs are stored literally in `<htmlView>` and in JSON property values (e.g., `jsonProperties.textTextarea` for `text` iDevices). They are never resolved to actual HTML paths inside `content.xml`.

At **export time** (`BaseExporter.ts:840–870`), the exporter replaces `exe-node:<pageId>` with the relative HTML path to the corresponding page. For multi-page exports this is a path like `html/page-title.html`; for single-page exports it becomes a fragment anchor.

At **import time** (`ElpxImporter.ts:1453–1479`), after all page IDs have been reassigned, `remapInternalPageLinks()` rewrites every `exe-node:<oldId>` reference to `exe-node:<newId>` using the `idRemap` built during `buildFlatPageList()`. The rewrite covers both `htmlView` strings and recursively walks JSON property objects via `remapLinksInObject()`.

---

## Annotated example: 1 root page + 1 child page with a text iDevice

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ode SYSTEM "content.dtd">
<ode xmlns="http://www.intef.es/xsd/ode" version="2.0">

  <userPreferences>
    <userPreference><key>theme</key><value>base</value></userPreference>
  </userPreferences>

  <odeResources>
    <odeResource><key>odeId</key><value>20260427120000PROJID</value></odeResource>
    <odeResource><key>odeVersionId</key><value>20260427120001VERSID</value></odeResource>
    <odeResource><key>exe_version</key><value>3.0</value></odeResource>
  </odeResources>

  <odeProperties>
    <odeProperty><key>pp_title</key><value>Example Project</value></odeProperty>
    <odeProperty><key>pp_lang</key><value>en</value></odeProperty>
  </odeProperties>

  <!-- Flat list: all pages at the same XML depth -->
  <odeNavStructures>

    <!-- Root page (odeParentPageId is empty) -->
    <odeNavStructure>
      <odePageId>20260427120002PAGEA1</odePageId>
      <odeParentPageId/>
      <pageName>Introduction</pageName>
      <odeNavStructureOrder>0</odeNavStructureOrder>

      <odeNavStructureProperties>
        <!-- titlePage always emitted (OdeXmlGenerator.ts:166) -->
        <odeNavStructureProperty>
          <key>titlePage</key><value>Introduction</value>
        </odeNavStructureProperty>
        <odeNavStructureProperty>
          <key>visibility</key><value>true</value>
        </odeNavStructureProperty>
      </odeNavStructureProperties>

      <odePagStructures>
        <odePagStructure>
          <!-- Redundant pageId: must equal enclosing odeNavStructure/odePageId -->
          <odePageId>20260427120002PAGEA1</odePageId>
          <odeBlockId>20260427120003BLKB1</odeBlockId>
          <blockName>Text</blockName>
          <iconName/>
          <odePagStructureOrder>0</odePagStructureOrder>

          <odePagStructureProperties>
            <!-- Fixed key list: visibility, teacherOnly, allowToggle, minimized, cssClass -->
            <odePagStructureProperty><key>visibility</key><value>true</value></odePagStructureProperty>
            <odePagStructureProperty><key>teacherOnly</key><value>false</value></odePagStructureProperty>
            <odePagStructureProperty><key>allowToggle</key><value>true</value></odePagStructureProperty>
            <odePagStructureProperty><key>minimized</key><value>false</value></odePagStructureProperty>
          </odePagStructureProperties>

          <odeComponents>
            <odeComponent>
              <!-- Both page and block IDs repeated; must match enclosing elements -->
              <odePageId>20260427120002PAGEA1</odePageId>
              <odeBlockId>20260427120003BLKB1</odeBlockId>
              <odeIdeviceId>20260427120004IDVC1</odeIdeviceId>
              <odeIdeviceTypeName>text</odeIdeviceTypeName>

              <!-- htmlView: always CDATA-wrapped by modern generator -->
              <htmlView><![CDATA[<div class="exe-text-template"><p>Hello world. <a href="exe-node:20260427120005PAGEB1">See section 2</a>.</p></div>]]></htmlView>

              <!-- jsonProperties: always CDATA-wrapped; link must also be updated on import -->
              <jsonProperties><![CDATA[{"textTextarea":"<p>Hello world. <a href=\"exe-node:20260427120005PAGEB1\">See section 2</a>.</p>"}]]></jsonProperties>

              <odeComponentsOrder>0</odeComponentsOrder>

              <odeComponentsProperties>
                <!-- Default when no structureProperties: visibility=true -->
                <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
              </odeComponentsProperties>
            </odeComponent>
          </odeComponents>
        </odePagStructure>
      </odePagStructures>
    </odeNavStructure>

    <!-- Child page: parent = Introduction -->
    <odeNavStructure>
      <odePageId>20260427120005PAGEB1</odePageId>
      <odeParentPageId>20260427120002PAGEA1</odeParentPageId>
      <pageName>Section 2</pageName>
      <odeNavStructureOrder>0</odeNavStructureOrder>

      <odeNavStructureProperties>
        <odeNavStructureProperty>
          <key>titlePage</key><value>Section 2</value>
        </odeNavStructureProperty>
        <odeNavStructureProperty>
          <key>visibility</key><value>true</value>
        </odeNavStructureProperty>
      </odeNavStructureProperties>

      <!-- Empty page: no blocks -->
      <odePagStructures/>
    </odeNavStructure>

  </odeNavStructures>
</ode>
```


# ===== doc/elpx-format/idevices/catalog.md =====

# iDevice Catalog

This document is the authoritative reference for all iDevice types available in eXeLearning. Each entry lists the modern type name used in `content.xml`, the display title, the category, and known legacy aliases accepted on import. Descriptions are written for authors and integrators who need to understand what each iDevice does without reading source code.

See also:
- [patterns.md](patterns.md) — how each iDevice stores its state in `content.xml`
- [config-xml.md](config-xml.md) — schema for the per-iDevice `config.xml` metadata file

---

## Master Table

| type | Title | Category | downloadable | api-version | component-type | Legacy aliases |
|------|-------|----------|-------------|-------------|----------------|----------------|
| `text` | Text | Information and presentation | 0 | 3.0 | json | `FreeTextIdevice`, `FreeTextfpdIdevice`, `ReflectionIdevice`, `ReflectionfpdIdevice`, `GenericIdevice`, `SolvedExerciseIdevice`, `WikipediaIdevice`, `RssIdevice` |
| `casestudy` | Case study | Information and presentation | 0 | 3.0 | json | `CaseStudyIdevice`, `CasopracticofpdIdevice` |
| `image-gallery` | Image gallery | Information and presentation | 0 | 3.0 | json | `ImageGalleryIdevice`, `GalleryIdevice` |
| `magnifier` | Magnifier | Information and presentation | 0 | 3.0 | json | `ImageMagnifierIdevice` |
| `external-website` | External website | Information and presentation | 0 | — | — | `ExternalUrlIdevice` |
| `download-source-file` | Download source file | Information and presentation | 0 | — | — | `FileAttachIdevice`, `FileAttachIdeviceInc`, `AttachmentIdevice` |
| `digcompedu` | DigCompEdu | Information and presentation | 0 | 3.0 | json | — |
| `map` | Map | Information and presentation | 0 | — | — | — |
| `udl-content` | UDL Content | Information and presentation | 0 | — | — | — |
| `example` | Example | Information and presentation | 1 | 3.0 | json | — |
| `trueorfalse` | True or false | Assessment and tracking | 0 | 3.0 | json | `TrueFalseIdevice`, `VerdaderoFalsoFPDIdevice`, `VerdaderofalsofpdIdevice` |
| `quick-questions` | Test | Assessment and tracking | 0 | — | — | `QuizTestIdevice`, `ScormTestIdevice` |
| `quick-questions-multiple-choice` | Select | Assessment and tracking | 0 | — | — | `MultichoiceIdevice`, `EleccionmultiplefpdIdevice` |
| `quick-questions-video` | Video test | Assessment and tracking | 0 | — | — | — |
| `interactive-video` | Interactive video | Assessment and tracking | 0 | — | — | — |
| `form` | Form | Assessment and tracking | 0 | 3.0 | json | `ClozeIdevice`, `ClozeActivityIdevice`, `ClozeLanguageIdevice`, `ClozeLangIdevice`, `MultiSelectIdevice`, `SeleccionmultiplefpdIdevice`, `ClozefpdIdevice`, `ClozelangfpdIdevice` |
| `guess` | Guess | Assessment and tracking | 0 | — | — | — |
| `checklist` | Checklist | Assessment and tracking | 0 | — | — | — |
| `rubric` | Rubric | Assessment and tracking | 0 | — | — | — |
| `select-media-files` | Select media files | Assessment and tracking | 0 | — | — | — |
| `progress-report` | Progress report | Assessment and tracking | 0 | — | — | — |
| `beforeafter` | Before/After | Interactive activities | 0 | — | — | — |
| `classify` | Classify | Interactive activities | 0 | — | — | — |
| `complete` | Complete | Interactive activities | 0 | — | — | — |
| `dragdrop` | Drag and drop | Interactive activities | 0 | — | — | — |
| `flipcards` | Memory cards | Interactive activities | 0 | — | — | — |
| `identify` | Identify | Interactive activities | 0 | — | — | — |
| `relate` | Relate | Interactive activities | 0 | — | — | — |
| `scrambled-list` | Scrambled list | Interactive activities | 0 | 3.0 | json | — |
| `sort` | Sort | Interactive activities | 0 | — | — | — |
| `az-quiz-game` | A-Z quiz | Games | 0 | — | — | — |
| `challenge` | Challenge | Games | 0 | — | — | — |
| `crossword` | Crossword | Games | 0 | — | — | — |
| `discover` | Discover | Games | 0 | — | — | — |
| `hidden-image` | Hidden image | Games | 0 | — | — | — |
| `padlock` | Padlock | Games | 0 | — | — | — |
| `puzzle` | Puzzle | Games | 0 | — | — | — |
| `trivial` | TriviExt | Games | 0 | — | — | — |
| `word-search` | Word search | Games | 0 | — | — | — |
| `geogebra-activity` | GeoGebra activity | Science | 0 | — | — | `GeogebraIdevice` |
| `mathematicaloperations` | Math operations | Science | 0 | — | — | — |
| `mathproblems` | Math problems | Science | 0 | — | — | — |
| `periodic-table` | Periodic table | Science | 0 | — | — | — |

Snippet links are deferred: [snippets.md#text](snippets.md#text), [snippets.md#casestudy](snippets.md#casestudy), etc.

A dash (`—`) in `api-version` or `component-type` means the field is absent from that iDevice's `config.xml`; such iDevices do not follow the full api-v3 lifecycle and store state differently. See [patterns.md](patterns.md) for details.

---

## Information and presentation

### `text`

The foundational iDevice. Accepts arbitrary rich HTML produced by the in-app editor, plus optional metadata fields (duration, grouping). The editor reads `jsonProperties` to restore the user's authored content; the rendered `htmlView` is what appears in exports. Handles most content that does not fit a more specific iDevice.

### `casestudy`

A structured presentation of a scenario together with its analysis. Presents the scenario text and a "What would you do?" or worked answer section side by side. Imported from legacy format via `CaseStudyIdevice`.

### `image-gallery`

A lightbox-enabled image gallery. Authors upload images and add captions; the export embeds `simple-lightbox.min.js` and `simple-lightbox.min.css` alongside the iDevice's own JS/CSS.

### `magnifier`

A zoom-on-hover magnifier for a single image. Useful for detailed diagrams or maps that learners need to inspect closely.

### `external-website`

Embeds a remote URL in an iframe. The author sets the URL, width, height, and whether to display a fallback error message when the iframe is blocked by HTTPS/HTTP mismatch.

### `download-source-file`

Presents a descriptive table about the learning resource and a button that downloads the original `.elpx` source file when the exported package includes it. The entire content is rendered into `htmlView` at export time; there is no separate JSON state blob.

### `digcompedu`

A DigCompEdu competence framework manager. Authors tag learning objectives against the European Digital Competence Framework for Educators (DigCompEdu). Stores competence selections in `jsonProperties`.

### `map`

Embeds an interactive map (typically Leaflet-based) with configurable markers and popups. Game state is stored as URI-encoded JSON in a `mapa-DataGame js-hidden` div. See [patterns.md#uri-encoded-json](patterns.md#uri-encoded-json).

### `udl-content`

A Universal Design for Learning (UDL) container. Provides separate authored `<section>` blocks for the three UDL principles: representation, action/expression, and engagement. Each section is a standalone HTML block inside `htmlView`. Unlike most iDevices, it carries no JSON state payload for game mechanics; all editable content is structured HTML.

### `example`

A reference implementation used as a skeleton when developing new iDevices (`downloadable=1`). Provides a bootstrap for the api-v3 lifecycle: `edition-js`, `export-js`, `export-template-filename`. Marked hidden by default (`<default-visibility>0</default-visibility>`).

---

## Assessment and tracking

### `trueorfalse`

Presents a statement and asks the learner to respond True or False. Supports optional feedback text for each answer. State is stored in `jsonProperties` as structured JSON; `htmlView` holds the rendered quiz.

### `quick-questions`

A multiple-choice test with a single correct answer per question (radio-button style). Game data is URI-encoded in a `quext-DataGame js-hidden` div inside `htmlView`.

### `quick-questions-multiple-choice`

A multiple-choice test where more than one answer can be correct (checkbox style). Game data lives in a `selecciona-DataGame js-hidden` div inside `htmlView`.

### `quick-questions-video`

A video player with inline quiz questions triggered at time-coded moments. Game data is in a `vquext-DataGame js-hidden` div inside `htmlView`.

### `interactive-video`

A video annotated with interactive slides (text annotations, single-choice questions, images) that appear at specified timestamps. JSON data is embedded inside a `<script id="exe-interactive-video-contents" type="application/json">` block (or, in older exports, a `<div id="exe-interactive-video-contents" style="display:none">` block) within `htmlView`. `jsonProperties` stores a separately maintained editor state. See [patterns.md#embedded-script-json](patterns.md#embedded-script-json).

### `form`

A free-form assessment container. Covers fill-in-the-blank, cloze activities, dropdown questions, and multi-select question sets. Legacy aliases include all FPD cloze variants and SCORM quiz types. State in `jsonProperties`.

### `guess`

A guessing activity where learners reveal a hidden answer step by step. Game data in `adivina-DataGame js-hidden`.

### `checklist`

A self-assessment checklist with configurable criteria. Game data in `listacotejo-DataGame js-hidden`.

### `rubric`

A scoring rubric table. The entire table is rendered into `htmlView` as static HTML at save time; there is no `jsonProperties` blob. The rubric editor writes directly to `htmlView`.

### `select-media-files`

An activity where learners select correct image or audio files in response to a prompt. Game data in `seleccionamedias-DataGame js-hidden`.

### `progress-report`

A learner progress-tracking dashboard. Aggregates SCORM scores or self-assessment data. Game data in `informe-DataGame js-hidden`.

---

## Interactive activities

### `beforeafter`

A split-image slider showing a "before" state on one side and an "after" state on the other. Authors upload two images and configure the initial divider position. Game data in `beforeafter-DataGame js-hidden`.

### `classify`

Learners drag items into labelled categories. Game data in `clasifica-DataGame js-hidden`.

### `complete`

A fill-in-the-blank activity where learners type missing words directly into the text. Game data in `completa-DataGame js-hidden`.

### `dragdrop`

A drag-and-drop activity where learners place labelled elements onto a background image at correct positions. Game data in `dragdrop-DataGame js-hidden`.

### `flipcards`

A memory-card game. Authors configure card fronts (images) and backs (text labels). Cards are randomizable. Game data in `flipcards-DataGame js-hidden`.

### `identify`

An image annotation activity where learners click on the correct region of an image to identify a labelled element. Game data in `identifica-DataGame js-hidden`.

### `relate`

A matching activity where learners draw connections between two columns of items. Game data in `relaciona-DataGame js-hidden`.

### `scrambled-list`

An ordering activity where learners drag list items into the correct sequence. Unlike most activity iDevices, `scrambled-list` stores its JSON state in `jsonProperties` (not as URI-encoded data in `htmlView`); the JSON uses key `typeGame: "ScrambledList"`. See [patterns.md](patterns.md) for the distinction.

### `sort`

A sorting activity where learners arrange cards or blocks in the correct order. Game data in `ordena-DataGame js-hidden`.

---

## Games

### `az-quiz-game`

A quiz game styled as an A-to-Z board. Each letter is associated with a question. Game data in `rosco-DataGame js-hidden`.

### `challenge`

A timed challenge game with multiple rounds of questions. Game data in `desafio-DataGame js-hidden`.

### `crossword`

An auto-generated crossword puzzle. Word/clue pairs are defined by the author; the crossword layout is computed at runtime. Game data in `crucigrama-DataGame js-hidden`.

### `discover`

A progressive image-reveal game. The image is covered by tiles that are removed as the learner answers questions correctly. Game data in `descubre-DataGame js-hidden`.

### `hidden-image`

An image that is covered and revealed by correct answers. Distinct from `discover` in layout and reveal mechanic. Game data in `hiddenimage-DataGame js-hidden`.

### `padlock`

A combination-lock game where the learner must enter a code discovered by answering questions. Game data in `candado-DataGame js-hidden`.

### `puzzle`

A jigsaw-puzzle activity where learners reassemble a scrambled image. Game data in `puzzle-DataGame js-hidden`.

### `trivial`

A trivia wheel game (TriviExt) with multiple categories arranged around a wheel. Game data in `trivial-DataGame js-hidden`.

### `word-search`

A word-search grid generated from an author-supplied word list. Game data in `sopa-DataGame js-hidden`.

---

## Science

### `geogebra-activity`

Embeds a GeoGebra applet (by GeoGebra ID or uploaded file) with optional auto-evaluation. State is in `jsonProperties`; the applet is rendered via the GeoGebra API at runtime.

### `mathematicaloperations`

An arithmetic practice activity where learners solve generated arithmetic operations. Game data in `mathoperations-DataGame js-hidden`.

### `mathproblems`

A word-problem activity for mathematics. Learners solve presented problems with numeric or symbolic answers. Game data in `mathproblems-DataGame js-hidden`.

### `periodic-table`

An interactive periodic table activity. Learners identify or classify elements. Game data in `periodic-table-DataGame js-hidden`.

---

## Legacy / FPD aliases

The following table lists every legacy CamelCase class name that the importer recognises and the modern type it maps to. Legacy names are accepted on import only and are rewritten to the modern type name before the document is stored. Source: `src/shared/import/legacy-handlers/HandlerRegistry.ts`.

| Legacy class name | Modern type |
|-------------------|-------------|
| `FreeTextIdevice` | `text` |
| `FreeTextfpdIdevice` | `text` |
| `ReflectionIdevice` | `text` |
| `ReflectionfpdIdevice` | `text` |
| `GenericIdevice` | `text` |
| `SolvedExerciseIdevice` | `text` |
| `EjercicioResueltoFpdIdevice` | `text` |
| `WikipediaIdevice` | `text` |
| `RssIdevice` | `text` |
| `MultichoiceIdevice` | `form` |
| `MultiSelectIdevice` | `form` |
| `ListaIdevice` | `form` |
| `ClozeIdevice` | `form` |
| `ClozeActivityIdevice` | `form` |
| `ClozeLanguageIdevice` | `form` |
| `ClozeLangIdevice` | `form` |
| `ScormTestIdevice` | `form` |
| `QuizTestIdevice` | `form` |
| `TrueFalseIdevice` | `trueorfalse` |
| `VerdaderoFalsoFPDIdevice` | `trueorfalse` |
| `CaseStudyIdevice` | `casestudy` |
| `ImageGalleryIdevice` | `image-gallery` |
| `GalleryIdevice` | `image-gallery` |
| `ImageMagnifierIdevice` | `magnifier` |
| `FileAttachIdevice` | `text` |
| `FileAttachIdeviceInc` | `text` |
| `AttachmentIdevice` | `text` |
| `ExternalUrlIdevice` | `external-website` |
| `GeogebraIdevice` | `geogebra-activity` |
| `JavaAppIdevice` | `java-app` |

Additional FPD-specific aliases recognised by the XSD but not explicitly mapped (they fall through to the kebab-case normalisation in `getLegacyTypeName()`):

`VerdaderofalsofpdIdevice`, `EleccionmultiplefpdIdevice`, `SeleccionmultiplefpdIdevice`, `ClozefpdIdevice`, `ClozelangfpdIdevice`, `ReflectionfpdmodifIdevice`, `TareasIdevice`, `ListaApartadosIdevice`, `ComillasIdevice`, `NotaInformacionIdevice`, `NotaIdevice`, `CasopracticofpdIdevice`, `CitasparapensarfpdIdevice`, `DebesconocerfpdIdevice`, `DestacadofpdIdevice`, `OrientacionestutoriafpdIdevice`, `OrientacionesalumnadofpdIdevice`, `ParasabermasfpdIdevice`, `RecomendacionfpdIdevice`, `EjercicioresueltofpdIdevice`.

Source for the full enumeration: `public/app/schemas/ode/ode-content.xsd` lines 158–234.


# ===== doc/elpx-format/idevices/patterns.md =====

# iDevice Content-Storage Patterns

This document describes the four ways iDevices store their state inside a `content.xml` `<odeComponent>` block. Understanding these patterns is required when writing tools that generate, parse, or round-trip ELPX files programmatically (e.g. AI generators, importers, automated test fixtures).

See also:
- [catalog.md](catalog.md) — full list of iDevice types and which pattern each one uses
- [config-xml.md](config-xml.md) — per-iDevice `config.xml` metadata schema

---

## Context: the `<odeComponent>` wrapper

Every iDevice in `content.xml` is enclosed in an `<odeComponent>` element. The wrapper carries four identification fields, then the content fields discussed below.

```xml
<odeComponent>
  <odePageId>20251025070914ABCDEF</odePageId>
  <odeBlockId>20251025070914XYZUVW</odeBlockId>
  <odeIdeviceId>20251025070914XDRVFP</odeIdeviceId>
  <odeIdeviceTypeName>text</odeIdeviceTypeName>
  <!-- content fields below -->
</odeComponent>
```

IDs use the format `YYYYMMDDHHmmss` + 6 uppercase alphanumeric characters. The `odeIdeviceTypeName` value is the modern type name from [catalog.md](catalog.md).

---

## Pattern 1: Standard JSON

### When it is used

Used by iDevices that have a structured editor backed by a JavaScript component with `component-type: json` in `config.xml`. The editor reads `jsonProperties` on open, modifies it in memory, and writes both `jsonProperties` and `htmlView` on save.

**Types using this pattern:** `text`, `casestudy`, `image-gallery`, `magnifier`, `trueorfalse`, `form`, `digcompedu`, `example`, `geogebra-activity`, `scrambled-list`, `udl-content`

### Structure

- `<htmlView>` — rendered HTML output, wrapped in `<![CDATA[ ... ]]>`. What the learner sees in the exported package. Regenerated from `jsonProperties` every time the iDevice is saved.
- `<jsonProperties>` — JSON string, wrapped in `<![CDATA[ ... ]]>`. The canonical editable state. The editor reads this; `htmlView` is derived from it.

Both values are **always** wrapped in CDATA in v4 — even when the content contains no XML-significant characters — because [`OdeXmlGenerator.ts:270, 275`](../../../src/shared/export/generators/OdeXmlGenerator.ts) emits the wrapper unconditionally. Inside the CDATA section, `<`, `>`, `"`, `&` are written verbatim (no entity encoding). The single exception is the literal three-character sequence `]]>`, which would close the CDATA section prematurely and is therefore split as `]]]]><![CDATA[>` by [`escapeCdata()`](../../../src/shared/export/generators/OdeXmlGenerator.ts).

### How to read it

```
raw_html   = odeComponent.htmlView.textContent           // already decoded by the XML parser
state_json = json_parse(odeComponent.jsonProperties.textContent)
```

`textContent` returns the CDATA payload verbatim — no further decoding is needed.

### How to write it

1. Build the JSON state object.
2. Render the HTML from the state object (apply the iDevice's template logic).
3. If either string contains the literal sequence `]]>`, split it as `]]]]><![CDATA[>` (the `escapeCdata` rule).
4. Wrap each value in `<![CDATA[ ... ]]>` and write into `<jsonProperties>` / `<htmlView>`.

### XML excerpt (type: `text`)

```xml
<odeComponent>
  <odePageId>20251027202947MKIISA</odePageId>
  <odeBlockId>20251027202947EDIAYV</odeBlockId>
  <odeIdeviceId>20251025070914XDRVFP</odeIdeviceId>
  <odeIdeviceTypeName>text</odeIdeviceTypeName>
  <htmlView>&lt;div class="exe-text-template"&gt;&lt;div class="textIdeviceContent"&gt;
    &lt;div class="exe-text-activity"&gt;
      &lt;div&gt;&lt;div class="exe-text"&gt;
        &lt;h1&gt;Manual de eXeLearning 3.0&lt;/h1&gt;
        &lt;p&gt;Guia practica para crear contenidos educativos.&lt;/p&gt;
      &lt;/div&gt;&lt;/div&gt;
    &lt;/div&gt;
  &lt;/div&gt;&lt;/div&gt;</htmlView>
  <jsonProperties>{"ideviceId":"20251025070914XDRVFP",
    "textInfoDurationInput":"",
    "textInfoParticipantsInput":"",
    "textInfoDurationTextInput":"Duracion",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"&lt;div class=\"exe-text\"&gt;\n&lt;h1&gt;Manual de eXeLearning 3.0&lt;/h1&gt;
      &lt;p&gt;Guia practica para crear contenidos educativos.&lt;/p&gt;\n&lt;/div&gt;"
  }</jsonProperties>
</odeComponent>
```

Note that `textTextarea` inside the JSON itself also HTML-entity-encodes its HTML content (double-encoded relative to the raw file bytes).

---

## Pattern 2: URI-encoded JSON inside `htmlView`

### When it is used

Used by game-type and complex interactive iDevices. The JSON state is `encodeURIComponent(JSON.stringify(data))` and placed inside a hidden `<div>` whose CSS class follows the naming convention `<internal-name>-DataGame js-hidden`. The `<jsonProperties>` element may be absent, empty, or may hold supplementary metadata (duration, grouping, ideviceId) that is not the primary game state.

**Types using this pattern:**

| type | DataGame class |
|------|----------------|
| `az-quiz-game` | `rosco-DataGame js-hidden` |
| `beforeafter` | `beforeafter-DataGame js-hidden` |
| `challenge` | `desafio-DataGame js-hidden` |
| `checklist` | `listacotejo-DataGame js-hidden` |
| `classify` | `clasifica-DataGame js-hidden` |
| `complete` | `completa-DataGame js-hidden` |
| `crossword` | `crucigrama-DataGame js-hidden` |
| `discover` | `descubre-DataGame js-hidden` |
| `dragdrop` | `dragdrop-DataGame js-hidden` |
| `flipcards` | `flipcards-DataGame js-hidden` |
| `guess` | `adivina-DataGame js-hidden` |
| `hidden-image` | `hiddenimage-DataGame js-hidden` |
| `identify` | `identifica-DataGame js-hidden` |
| `map` | `mapa-DataGame js-hidden` |
| `mathematicaloperations` | `mathoperations-DataGame js-hidden` |
| `mathproblems` | `mathproblems-DataGame js-hidden` |
| `padlock` | `candado-DataGame js-hidden` |
| `periodic-table` | `periodic-table-DataGame js-hidden` |
| `progress-report` | `informe-DataGame js-hidden` |
| `puzzle` | `puzzle-DataGame js-hidden` |
| `quick-questions` | `quext-DataGame js-hidden` |
| `quick-questions-multiple-choice` | `selecciona-DataGame js-hidden` |
| `quick-questions-video` | `vquext-DataGame js-hidden` |
| `relate` | `relaciona-DataGame js-hidden` |
| `select-media-files` | `seleccionamedias-DataGame js-hidden` |
| `sort` | `ordena-DataGame js-hidden` |
| `trivial` | `trivial-DataGame js-hidden` |
| `word-search` | `sopa-DataGame js-hidden` |

### Structure

Inside `<htmlView>`, the rendered HTML includes a hidden `<div>` that holds the URI-encoded game data:

```html
<div class="<name>-DataGame js-hidden">%7B%22typeGame%22%3A%22...</div>
```

The value is `encodeURIComponent(JSON.stringify(gameData))`. The `%`-encoded payload sits inside the CDATA section of `<htmlView>`, so the percent-encoding flows through the XML serialisation untouched (CDATA does not reinterpret `%`, `<`, or any other character).

### How to read it

```
raw_html    = odeComponent.htmlView.textContent       // CDATA body — verbatim
dom         = parse_html(raw_html)
div         = dom.querySelector('[class*="DataGame"][class*="js-hidden"]')
game_data   = json_parse(decodeURIComponent(div.textContent.trim()))
```

### How to write it

1. Build the game data JSON object.
2. `encoded = encodeURIComponent(JSON.stringify(gameData))`
3. Inject the string as the text content of the `<div class="<name>-DataGame js-hidden">` element inside the full rendered HTML.
4. HTML-entity-encode the full HTML and write it into `<xmlView>`.
5. If the iDevice also uses `<jsonProperties>` for supplementary metadata (ideviceId, duration, grouping), write that separately using Pattern 1 encoding for those fields.

### XML excerpt (type: `flipcards`)

```xml
<odeComponent>
  <odePageId>20251021091936PQRSTU</odePageId>
  <odeBlockId>20251021091936ABCXYZ</odeBlockId>
  <odeIdeviceId>20251021091936VCTATJ</odeIdeviceId>
  <odeIdeviceTypeName>flipcards</odeIdeviceTypeName>
  <htmlView>&lt;div class="flipcards-IDevice"&gt;
    &lt;div class="flipcards-instructions gameQP-instructions"&gt;
      &lt;p&gt;Haz clic sobre cada carta para descubrir el nombre de su animal&lt;/p&gt;
    &lt;/div&gt;
    &lt;div class="flipcards-DataGame js-hidden"&gt;%7B%22typeGame%22%3A%22FlipCards%22%2C
      %22author%22%3A%22%22%2C%22randomCards%22%3Atrue%2C%22instructions%22%3A%22...%22%2C
      %22cardsGame%22%3A%5B%7B%22url%22%3A%22...%22%7D%5D%7D
    &lt;/div&gt;
  &lt;/div&gt;</htmlView>
  <jsonProperties>{"ideviceId":"20251021091936VCTATJ",
    "textInfoDurationInput":"",
    "textInfoParticipantsInput":""}</jsonProperties>
</odeComponent>
```

Decoded, the DataGame div text is:
```json
{
  "typeGame": "FlipCards",
  "author": "",
  "randomCards": true,
  "instructions": "<p>Haz clic sobre cada carta...</p>",
  "cardsGame": [{ "url": "{{context_path}}/..." }]
}
```

#### Note on `crossword` and some other games

Some games (`crossword`, `hidden-image`, `puzzle`, `beforeafter`, `dragdrop`, `periodic-table`) have `<jsonProperties>` absent entirely (not just empty). The DataGame div in `<htmlView>` is the only source of truth for those types.

---

## Pattern 3: Embedded JSON block in `htmlView`

### When it is used

Used by `interactive-video` (and the related `quick-questions-video` in some export versions). The JSON data for interactive slides is embedded directly inside `<htmlView>` as the content of a specially identified element, rather than URI-encoded in a DataGame div.

**Types using this pattern:** `interactive-video`

### Structure

There are two sub-variants depending on eXeLearning version:

**Modern (v3.x exports):** a `<script>` tag with `type="application/json"`:
```html
<script id="exe-interactive-video-contents" type="application/json">
  {"slides": [...], "i18n": {...}}
</script>
```

**Older exports:** a `<div>` with `style="display:none"`:
```html
<div id="exe-interactive-video-contents" style="display: none">
  {"slides": [...], "i18n": {...}}
</div>
```

Both are inside the CDATA-wrapped `<htmlView>`. The `<jsonProperties>` element is also present (also CDATA-wrapped) and holds a separately maintained editor copy of the video configuration; the two may diverge if the user edits one path and not the other.

### How to read it

```
raw_html  = odeComponent.htmlView.textContent       // CDATA body — verbatim
dom       = parse_html(raw_html)
el        = dom.getElementById('exe-interactive-video-contents')
slides    = json_parse(el.textContent.trim())
```

### How to write it

1. Build the slides JSON object.
2. Serialize to a JSON string (no URI encoding needed).
3. Place the JSON string as the text content of `<script id="exe-interactive-video-contents" type="application/json">` inside the full HTML structure.
4. HTML-entity-encode the full HTML and write into `<htmlView>`.
5. Write matching state into `<jsonProperties>` using Pattern 1 encoding.

### XML excerpt (type: `interactive-video`)

```xml
<odeComponent>
  <odeIdeviceId>20251027120355IWQHYP</odeIdeviceId>
  <odeIdeviceTypeName>interactive-video</odeIdeviceTypeName>
  <htmlView>&lt;div class="exe-interactive-video-content-before"&gt;
    &lt;p&gt;Video sobre el suelo&lt;/p&gt;
    &lt;/div&gt;
    &lt;div class="game-evaluation-ids js-hidden"
         data-id="20251027120355IWQHYP"
         data-evaluationb="false" data-evaluationid=""&gt;&lt;/div&gt;
    &lt;div class="exe-interactive-video"&gt;
      &lt;p id="exe-interactive-video-file" class="js-hidden"&gt;
        &lt;a href="https://www.youtube.com/watch?v=ALO_ukssQLg"&gt;
          com/watch?v=ALO_ukssQLg&lt;/a&gt;
      &lt;/p&gt;
      &lt;script id="exe-interactive-video-contents"
              type="application/json"&gt;
        {"slides":[
          {"type":"text","text":"&lt;p&gt;Por que es tan importante el suelo?&lt;/p&gt;",
           "startTime":45,"current":false},
          {"type":"image","url":1,"description":"Formacion del suelo",
           "startTime":118}
        ],"i18n":{"start":"Empezar","results":"Resultado"}}
      &lt;/script&gt;
    &lt;/div&gt;</htmlView>
  <jsonProperties>{"ideviceId":"20251027120355IWQHYP",
    "textInfoDurationInput":"","textInfoParticipantsInput":"",
    "textTextarea":"&lt;div class=\"exe-interactive-video ...\"&gt;..."
  }</jsonProperties>
</odeComponent>
```

---

## Pattern 4: `htmlView`-only

### When it is used

Used by iDevices where the entire editable content is rendered HTML with no separate machine-readable JSON state. The editor writes HTML directly; on re-edit it parses the HTML back.

**Types using this pattern:** `rubric`, `external-website`, `download-source-file`

Note: `udl-content` has `<jsonProperties>` present (Pattern 1) but the HTML in `htmlView` contains multiple `<section>` blocks representing the UDL principles. The JSON state stores the same HTML sections. This is still Pattern 1, not Pattern 4.

### Structure

- `<htmlView>` — the complete rendered HTML, wrapped in `<![CDATA[ ... ]]>` like every other `htmlView`.
- `<jsonProperties>` — absent or empty.

### How to read it

```
raw_html = odeComponent.htmlView.textContent        // CDATA body — verbatim
```

There is no secondary JSON to decode. Any structured data (iframe URL for `external-website`, table content for `rubric`) must be parsed from the HTML directly.

### How to write it

1. Build the HTML string directly.
2. HTML-entity-encode it.
3. Write into `<htmlView>`. Omit or leave empty the `<jsonProperties>` element.

### XML excerpt (type: `external-website`)

```xml
<odeComponent>
  <odeIdeviceId>20251021091936EXTURL</odeIdeviceId>
  <odeIdeviceTypeName>external-website</odeIdeviceTypeName>
  <htmlView>&lt;div id="iframeWebsiteIdevice"&gt;
    &lt;iframe src="https://cedec.intef.es/"
            width="600" height="300"
            style="width:100%;"&gt;
    &lt;/iframe&gt;
    &lt;div class="iframe-error-message" style="display:none;"&gt;
      No se puede mostrar un iframe en HTTP en una web HTTPS.
    &lt;/div&gt;
  &lt;/div&gt;</htmlView>
</odeComponent>
```

### XML excerpt (type: `rubric`)

```xml
<odeComponent>
  <odeIdeviceId>20251021091936RUBRIC</odeIdeviceId>
  <odeIdeviceTypeName>rubric</odeIdeviceTypeName>
  <htmlView>&lt;table class='exe-table'&gt;
    &lt;caption&gt;Rubrica para evaluar un trabajo escrito&lt;/caption&gt;
    &lt;thead&gt;&lt;tr&gt;
      &lt;th&gt;&amp;nbsp;&lt;/th&gt;
      &lt;th&gt;4 Excelente&lt;/th&gt;
      &lt;th&gt;3 Satisfactorio&lt;/th&gt;
      &lt;th&gt;2 Mejorable&lt;/th&gt;
      &lt;th&gt;1 Insuficiente&lt;/th&gt;
    &lt;/tr&gt;&lt;/thead&gt;
    &lt;tbody&gt;
      &lt;tr&gt;
        &lt;th&gt;Aspectos formales&lt;/th&gt;
        &lt;td&gt;Se presenta en plazo ...&lt;/td&gt;
        ...
      &lt;/tr&gt;
    &lt;/tbody&gt;
  &lt;/table&gt;</htmlView>
</odeComponent>
```

---

## Edge cases and caveats

### `scrambled-list`: Pattern 1 with game-flavoured JSON

`scrambled-list` is classified as Pattern 1 (standard JSON in `jsonProperties`). However its JSON payload uses a `typeGame` field (`"typeGame": "ScrambledList"`) similar to DataGame payloads. This is not URI-encoded; the JSON is written directly into `<jsonProperties>`. The `htmlView` contains the rendered sortable list HTML but no `*-DataGame js-hidden` div.

### `geogebra-activity`: Pattern 1, but `htmlView` has DataGame-style evaluation div

`geogebra-activity` uses Pattern 1 (JSON in `jsonProperties`). The `htmlView` may contain a `game-evaluation-ids js-hidden` div for SCORM scoring, but the main configuration state is in `jsonProperties`.

### `quick-questions-video`: DataGame in `htmlView`

Despite the name similarity to `interactive-video`, `quick-questions-video` uses Pattern 2 (DataGame, `vquext-DataGame js-hidden`), not Pattern 3.

### Asset path placeholder `{{context_path}}`

Image and media URLs inside both `htmlView` and `jsonProperties` use `{{context_path}}/` as a prefix, followed by the iDevice ID and filename. At export time the exporter replaces `{{context_path}}` with the relative path to the assets directory.

---

## Decision cheat-sheet: which pattern for a new iDevice?

```
Does the iDevice have a structured JSON editor
with component-type=json in config.xml?
    YES --> Does it use a game runtime that needs
            URI-encoded state in the DOM?
                YES --> Pattern 2 (DataGame)
                NO  --> Is the state a video slide deck?
                            YES --> Pattern 3 (embedded script/div)
                            NO  --> Pattern 1 (standard JSON)
    NO  --> Pattern 4 (htmlView-only)
```

Quick rules:
- Simple content iDevices (text, case study, gallery, magnifier): **Pattern 1**.
- Game/activity iDevices with a game engine (flipcards, crossword, quiz, sort, etc.): **Pattern 2**.
- Interactive video only: **Pattern 3**.
- Legacy presentational iDevices with no JSON model (rubric, iframe embed, file download): **Pattern 4**.


# ===== doc/elpx-format/idevices/config-xml.md =====

# iDevice `config.xml` Schema

Every iDevice type ships a `config.xml` file located at:

```
public/files/perm/idevices/base/<type>/config.xml
```

This file is metadata only. It tells the eXeLearning runtime how to load, render, and export the iDevice. The actual interactive logic lives in the JS, CSS, and HTML template files referenced by `<edition-*>` and `<export-*>` elements.

See also:
- [catalog.md](catalog.md) — complete iDevice type catalog with values sourced from these files
- [patterns.md](patterns.md) — how iDevices store their state in `content.xml`
- [doc/development/styles.md](../../development/styles.md) — theming and CSS class conventions

---

## Element reference

| Element | Required | Type | Description |
|---------|----------|------|-------------|
| `<idevice>` | yes | element | Root element. All other elements are direct children. |
| `<name>` | no | string | Internal programmatic name. When absent the runtime uses the directory name as the type identifier. Usually matches the directory name (e.g. `text`, `digcompedu`). |
| `<title>` | yes | string | Human-readable display name shown in the iDevice panel. Localised at runtime by the i18n layer. |
| `<css-class>` | yes | string | CSS class added to the iDevice's root `<div>` in both the editor and exports. Conventionally equals the type name. Used by themes for per-type styling; see [styles.md](../../development/styles.md). |
| `<category>` | yes | string | Category group shown in the iDevice panel. One of: `Information and presentation`, `Interactive activities`, `Games`, `Assessment and tracking`, `Science`. |
| `<icon>` | yes | element | Container for icon metadata. Has three children: `<name>` (CSS/icon identifier), `<url>` (SVG filename relative to the iDevice directory), `<type>` (always `img` for SVG icons). Older iDevices may use a bare string value (e.g. `<icon>lightbulb</icon>`) instead of the structured form. |
| `<icon>/<name>` | yes* | string | Icon identifier (e.g. `text-icon`). Used as a CSS class or aria-label. |
| `<icon>/<url>` | yes* | string | Filename of the SVG icon (e.g. `text-icon.svg`). Resolved relative to the iDevice directory. |
| `<icon>/<type>` | yes* | string | Always `img` for SVG-based icons. |
| `<version>` | no | string | iDevice version string (e.g. `1.0`). Informational only; not used for compatibility checks. |
| `<api-version>` | no | string | API contract version. `3.0` indicates the iDevice supports the modern edition/export lifecycle (JS component, JSON state, HTML template). Absent on legacy or simple iDevices. |
| `<component-type>` | no | enum | Specifies how the editor manages state. `json` means the editor reads/writes `jsonProperties` in `content.xml`. Other possible values are `html` (editor manages HTML directly). Absent on iDevices that do not follow the api-v3 lifecycle. |
| `<location>` | no | string | Placeholder field. Present on api-v3 iDevices; value is the literal string `location`. Not used by the runtime. |
| `<location-type>` | no | string | Placeholder field. Present on api-v3 iDevices; value is the literal string `location type`. Not used by the runtime. |
| `<edition-js>` | no | element | JS file(s) loaded in the editor for this iDevice. Contains one or more `<filename>` children. Paths are relative to the iDevice directory. |
| `<edition-js>/<filename>` | no | string | Filename of an editor JS file (e.g. `text.js`). May repeat for multiple files. |
| `<edition-css>` | no | element | CSS file(s) loaded in the editor. Contains one or more `<filename>` children. |
| `<edition-css>/<filename>` | no | string | Filename of an editor CSS file (e.g. `text.css`). May repeat. |
| `<export-js>` | no | element | JS file(s) bundled into exports (HTML5, SCORM, EPUB3). Contains one or more `<filename>` children. A type may bundle third-party libraries here (e.g. `image-gallery` bundles `simple-lightbox.min.js`). |
| `<export-js>/<filename>` | no | string | Filename of an export JS file. May repeat. |
| `<export-css>` | no | element | CSS file(s) bundled into exports. Contains one or more `<filename>` children. |
| `<export-css>/<filename>` | no | string | Filename of an export CSS file. May repeat. |
| `<export-template-filename>` | no | string | Filename of the Nunjucks/HTML template used to render the iDevice in exports (e.g. `text.html`). |
| `<export-object>` | no | string | JavaScript global variable name used by the export engine to call into the iDevice's export logic (e.g. `$Digcompedu`). Rarely present. |
| `<author>` | no | string | Author name. Informational; appears in iDevice metadata UI. |
| `<author-url>` | no | string | URL to the author's page. Informational. |
| `<license>` | no | string | License identifier (e.g. `AGPL-3.0-or-later`). Informational. |
| `<license-url>` | no | string | URL to the license text. Informational. |
| `<description>` | no | string | Short description of the iDevice's purpose. May be empty. Shown in the iDevice panel tooltip and (for downloadable iDevices) in the download listing. |
| `<downloadable>` | yes | `0` or `1` | Whether the iDevice can be downloaded as a standalone package from the iDevice store. `1` means downloadable. All built-in iDevices currently have `0` except `example` which has `1`. |
| `<default-visibility>` | no | `0` or `1` | When `0`, the iDevice is hidden from the iDevice panel by default and only visible in developer/advanced mode. Used by `example`. |

\* Required when `<icon>` uses the structured child-element form rather than the legacy bare-string form.

---

## Annotated example: `text/config.xml`

This is the `text` iDevice, the simplest full api-v3 iDevice. File location: `public/files/perm/idevices/base/text/config.xml`.

```xml
<?xml version="1.0"?>
<idevice>
    <!-- Internal identifier; matches the directory name -->
    <name>text</name>

    <!-- Display title shown in the iDevice panel -->
    <title>Text</title>

    <!-- CSS class on the iDevice root div; used for theme overrides -->
    <css-class>text</css-class>

    <!-- Panel category -->
    <category>Information and presentation</category>

    <!-- SVG icon descriptor -->
    <icon>
        <name>text-icon</name>
        <url>text-icon.svg</url>
        <type>img</type>
    </icon>

    <!-- Version strings -->
    <version>1.0</version>
    <api-version>3.0</api-version>

    <!-- State management: reads/writes jsonProperties in content.xml -->
    <component-type>json</component-type>

    <!-- Placeholder fields (required by api-v3 schema but unused at runtime) -->
    <location>location</location>
    <location-type>location type</location-type>

    <!-- Editor assets: loaded when the user opens this iDevice for editing -->
    <edition-js>
        <filename>text.js</filename>
    </edition-js>
    <edition-css>
        <filename>text.css</filename>
    </edition-css>

    <!-- Export assets: bundled into every exported package -->
    <export-js>
        <filename>text.js</filename>
    </export-js>
    <export-css>
        <filename>text.css</filename>
    </export-css>

    <!-- Nunjucks template used to render the iDevice in exports -->
    <export-template-filename>text.html</export-template-filename>

    <!-- Authorship/licensing metadata (informational) -->
    <author>author</author>
    <author-url>author url</author-url>
    <license>license</license>
    <license-url>license url</license-url>

    <!-- Description shown in panel tooltip -->
    <description>Text component for bootstrap functionalities</description>

    <!-- Not downloadable from iDevice store -->
    <downloadable>0</downloadable>
</idevice>
```

---

## Annotated example: `image-gallery/config.xml`

This example shows multiple `<filename>` entries in `<export-js>` and `<export-css>` for a type that bundles a third-party library (`simple-lightbox`).

```xml
<?xml version="1.0"?>
<idevice>
    <name>image-gallery</name>
    <title>Image gallery</title>
    <css-class>image-gallery</css-class>
    <category>Information and presentation</category>

    <icon>
        <name>image-gallery</name>
        <url>image-gallery-icon.svg</url>
        <type>img</type>
    </icon>

    <version>1.0</version>
    <api-version>3.0</api-version>
    <component-type>json</component-type>
    <location>location</location>
    <location-type>location type</location-type>

    <edition-js>
        <filename>image-gallery.js</filename>
    </edition-js>
    <edition-css>
        <filename>image-gallery.css</filename>
    </edition-css>

    <!-- Two JS files bundled in exports: iDevice code + third-party lightbox -->
    <export-js>
        <filename>image-gallery.js</filename>
        <filename>simple-lightbox.min.js</filename>
    </export-js>

    <!-- Two CSS files bundled in exports -->
    <export-css>
        <filename>image-gallery.css</filename>
        <filename>simple-lightbox.min.css</filename>
    </export-css>

    <export-template-filename>image-gallery.html</export-template-filename>

    <author>author</author>
    <author-url>author url</author-url>
    <license>license</license>
    <license-url>license url</license-url>
    <description></description>
    <downloadable>0</downloadable>
</idevice>
```

---

## Minimal config.xml (no api-v3 lifecycle)

Many iDevices — particularly game-type and legacy iDevices — have a minimal `config.xml` that omits `<api-version>`, `<component-type>`, and all `<edition-*>` / `<export-*>` elements. Their JS/CSS is loaded through a different mechanism (the iDevice's own bootstrap script). Example (`crossword/config.xml`):

```xml
<?xml version="1.0"?>
<idevice>
    <title>Crossword</title>
    <css-class>crossword</css-class>
    <category>Games</category>
    <icon>
        <name>crossword-icon</name>
        <url>crossword-icon.svg</url>
        <type>img</type>
    </icon>
    <downloadable>0</downloadable>
</idevice>
```

For these iDevices the runtime infers the type name from the directory name. State storage follows Pattern 2 (URI-encoded DataGame); see [patterns.md](patterns.md).

---

## Downloadable iDevice example: `example/config.xml`

The `example` iDevice demonstrates all optional fields, including `<downloadable>1</downloadable>` and `<default-visibility>0</default-visibility>`. It is intended as a developer bootstrap template. File: `public/files/perm/idevices/base/example/config.xml`.

```xml
<?xml version="1.0"?>
<idevice>
    <name>example</name>
    <title>Example</title>
    <css-class>example</css-class>
    <category>Information and presentation</category>
    <icon>lightbulb</icon>   <!-- legacy bare-string icon form -->
    <version>1.0</version>
    <api-version>3.0</api-version>
    <component-type>json</component-type>
    <location>location</location>
    <location-type>location type</location-type>
    <edition-js>
        <filename>example.js</filename>
    </edition-js>
    <edition-css>
        <filename>example.css</filename>
    </edition-css>
    <export-js>
        <filename>example.js</filename>
    </export-js>
    <export-css>
        <filename>example.css</filename>
    </export-css>
    <export-template-filename>example.html</export-template-filename>
    <author>author</author>
    <author-url>author url</author-url>
    <license>license</license>
    <license-url>license url</license-url>
    <description>Example component for bootstrap functionalities</description>
    <!-- Downloadable from iDevice store -->
    <downloadable>1</downloadable>
    <!-- Hidden in panel by default; visible only in developer mode -->
    <default-visibility>0</default-visibility>
</idevice>
```

---

## Notes for iDevice authors

- The `config.xml` is never shipped inside exported packages. It is read by the editor at load time to register the iDevice type.
- `<edition-js>` and `<edition-css>` files are loaded only inside the editor iframe. They must not assume a global document context outside the editor panel.
- `<export-js>` and `<export-css>` files are copied verbatim into every exported package. Keep them self-contained and free of editor-only APIs.
- The `<css-class>` value becomes the BEM block name for theme authors. Themes can override per-iDevice styles using `.exe-<css-class>` selectors. See [styles.md](../../development/styles.md).
- `<description>` is the text surfaced in the iDevice help tooltip. Write it in English; the i18n pipeline picks it up via `make translations`. See [doc/development/internationalization.md](../../development/internationalization.md).


# ===== doc/elpx-format/idevices/snippets.md =====

# iDevice XML Snippets

This document provides a representative `<odeComponent>` block for every iDevice type available in eXeLearning. Each snippet is taken verbatim (or lightly trimmed) from the project's own test fixtures and can be used as a starting point when constructing or validating `.elpx` archives by hand or programmatically.

An `<odeComponent>` element is the atomic unit of iDevice storage inside `content.xml`. It lives inside an `<odeComponents>` list on a page (`<odePage>`). The five child elements that always appear are `<odePageId>`, `<odeBlockId>`, `<odeIdeviceId>`, `<odeIdeviceTypeName>`, and `<odeComponentsOrder>`. The two storage fields are `<htmlView>` (the pre-rendered HTML the export engine uses directly) and `<jsonProperties>` (the editable source data the editor reads back). The `<odeComponentsProperties>` list carries per-instance flags such as `visibility`, `teacherOnly`, `identifier`, and `cssClass`.

The four storage patterns referenced throughout this document are defined in [`patterns.md`](patterns.md). In brief: **Standard JSON** means `<jsonProperties>` holds a JSON object whose keys are the editable fields; **URI-encoded JSON in hidden div** means the game data is percent-encoded inside a hidden `<div>` inside `<htmlView>` and `<jsonProperties>` contains only a thin metadata wrapper (`textTextarea`, `textFeedbackTextarea`, etc.) that wraps the same HTML; **htmlView-only** means `<jsonProperties/>` is self-closing and the export HTML is the sole source of truth; **embedded `<script type="application/json">`** means a JSON block is inlined in `<htmlView>`.

IDs (page, block, idevice) follow the pattern `YYYYMMDDHHMMSS` + six uppercase alphanumeric characters. Generate fresh IDs when creating new components.

---

## az-quiz-game

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215OHOSFQ</odePageId>
  <odeBlockId>20251022181215ATVRXU</odeBlockId>
  <odeIdeviceId>20250605150704FPKNJN</odeIdeviceId>
  <odeIdeviceTypeName>az-quiz-game</odeIdeviceTypeName>
  <htmlView>
    <!-- Pre-rendered game HTML. The actual question data is stored as
         URI-percent-encoded JSON inside a hidden div with class
         "rosco-DataGame js-hidden". The wrapper iDevice HTML is also
         embedded in jsonProperties.textTextarea. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties>{"ideviceId":"20250605150704FPKNJN",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML, same as htmlView) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The A-Z quiz (Rosco) iDevice stores all question data as URI-percent-encoded JSON inside the hidden div `class="rosco-DataGame js-hidden"` within `htmlView`. The `jsonProperties` object is a thin metadata wrapper: `textTextarea` duplicates the full rendered HTML, while `textInfoDurationInput` and `textInfoParticipantsInput` carry optional lesson-info annotations. To create a new instance, encode the question array as percent-encoded JSON and embed it in the hidden div; regenerate `textTextarea` to match.

---

## beforeafter

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215PMQHWS</odePageId>
  <odeBlockId>20251022181215CYZARX</odeBlockId>
  <odeIdeviceId>20250605150704UOKBEL</odeIdeviceId>
  <odeIdeviceTypeName>beforeafter</odeIdeviceTypeName>
  <htmlView>
    <!-- Before/After comparison slider. Two images are embedded directly
         in the HTML; no separate jsonProperties data store is used. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The before/after iDevice uses the htmlView-only pattern: `<jsonProperties/>` is self-closing and all content, including the two image paths and slider configuration, is encoded directly inside the `<htmlView>` HTML. The editor reconstructs the form from the live DOM rather than from a JSON snapshot.

---

## casestudy

**Storage pattern:** Standard JSON | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-manual/content.xml`

```xml
<odeComponent>
  <odePageId>20251027202947UJFTPM</odePageId>
  <odeBlockId>20251027202947OWIMTQ</odeBlockId>
  <odeIdeviceId>20251022092535737VOP</odeIdeviceId>
  <odeIdeviceTypeName>casestudy</odeIdeviceTypeName>
  <htmlView>
    <!-- Rendered case-study HTML with history block and activity sections.
         Content trimmed; full HTML includes CSP-History and CSP-Activities divs. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties>{"id":"20251022092535737VOP",
    "typeGame":"Case study",
    "history":"&lt;p&gt;Narrative HTML...&lt;/p&gt;",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "activities":[
      {
        "activity":"&lt;h4&gt;Activity title&lt;/h4&gt;&lt;p&gt;...&lt;/p&gt;",
        "feedback":"&lt;p&gt;Feedback text&lt;/p&gt;",
        "buttonCaption":"Mostrar retroalimentación"
      }
    ]
  }
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The case-study iDevice uses Standard JSON. The key `history` holds the narrative rich-text HTML as a JSON string (the surrounding `<jsonProperties>` is CDATA-wrapped, so the HTML's `<`, `>`, `&` characters are written verbatim — only standard JSON-string escaping for `\"`, `\\`, and control characters applies). The `activities` array contains objects with `activity` (task description HTML), `feedback` (collapsible feedback HTML), and `buttonCaption` (button label). Both `textInfoDurationInput` and `textInfoParticipantsInput` are optional metadata fields.

---

## challenge

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215GEXCXT</odePageId>
  <odeBlockId>20251022181215PPHGQR</odeBlockId>
  <odeIdeviceId>20250605150704CKIQUR</odeIdeviceId>
  <odeIdeviceTypeName>challenge</odeIdeviceTypeName>
  <htmlView>
    <!-- Escape-room style multi-challenge activity. Contains:
         - class="desafio-IDevice" outer wrapper
         - class="desafio-instructions" introduction text
         - class="desafio-EDescription" overall narrative (rich HTML)
         - one or more class="desafio-ChallengeDescription" sections, each
           containing a challenge description and an embedded iframe/activity
         Challenge answer data is URI-encoded in a hidden div. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The challenge iDevice stores all content inside `htmlView` only — `<jsonProperties/>` is self-closing. The outer wrapper uses `class="desafio-IDevice"`. Multiple challenge stages appear as sibling `desafio-ChallengeDescription` divs. The final answer to the overall mystery is stored URI-encoded in a hidden element inside the rendered HTML.

---

## checklist

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215JPWLEU</odePageId>
  <odeBlockId>20251022181215FDBAJP</odeBlockId>
  <odeIdeviceId>20250605150704XPLIIS</odeIdeviceId>
  <odeIdeviceTypeName>checklist</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704XPLIIS",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML including checklist data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The checklist iDevice follows the URI-encoded JSON in hidden div pattern. `jsonProperties.textTextarea` stores the full iDevice HTML (identical to `htmlView`), which contains the checklist items URI-encoded in a hidden div. The `textFeedbackTextarea` field holds optional post-activity feedback HTML.

---

## classify

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215BBAAWJ</odePageId>
  <odeBlockId>20251022181215PZBPBU</odeBlockId>
  <odeIdeviceId>20250605150704FPXAIS</odeIdeviceId>
  <odeIdeviceTypeName>classify</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704FPXAIS",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with classify game data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The classify iDevice uses the URI-encoded JSON in hidden div pattern. Items to be sorted into categories are stored as percent-encoded JSON in a hidden div within `textTextarea`/`htmlView`. `jsonProperties` carries only the metadata wrapper keys.

---

## complete

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215TBKRKL</odePageId>
  <odeBlockId>20251022181215COMZUS</odeBlockId>
  <odeIdeviceId>20250605150704UCOOBV</odeIdeviceId>
  <odeIdeviceTypeName>complete</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704UCOOBV",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with fill-in data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The complete (fill-in-the-blanks) iDevice uses the URI-encoded JSON in hidden div pattern. The blanked text and expected answers are stored as percent-encoded JSON in a hidden div inside the rendered HTML. `jsonProperties.textTextarea` mirrors `htmlView` exactly; only the thin metadata keys (`textInfoDurationInput`, etc.) are separate editable fields.

---

## crossword

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215GMHSIA</odePageId>
  <odeBlockId>20251022181215PIOZFH</odeBlockId>
  <odeIdeviceId>20250605150704JMURGS</odeIdeviceId>
  <odeIdeviceTypeName>crossword</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704JMURGS",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with crossword grid data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The crossword iDevice uses URI-encoded JSON in hidden div. The crossword grid layout, word list, and clues are stored as percent-encoded JSON in a hidden div within `textTextarea`. The `teacherOnly` property appears explicitly in this iDevice's `<odeComponentsProperties>` (set to `false` by default).

---

## digcompedu

**Storage pattern:** Standard JSON | **Downloadable:** no

Not present in fixtures — minimal skeleton based on `public/files/perm/idevices/base/digcompedu/edition/digcompedu.js` (source: `digcompedu.js:init`).

```xml
<odeComponent>
  <odePageId>YYYYMMDDHHMMSSAAAAAA</odePageId>
  <odeBlockId>YYYYMMDDHHMMSSBBBBBB</odeBlockId>
  <odeIdeviceId>YYYYMMDDHHMMSSCCCCCC</odeIdeviceId>
  <odeIdeviceTypeName>digcompedu</odeIdeviceTypeName>
  <htmlView>
    <!-- Rendered DigCompEdu summary table HTML, generated by the
         export template digcompedu.html from the saved JSON data. -->
    &lt;div class="digcompedu-container"&gt;
      &lt;!-- summary table rendered here --&gt;
    &lt;/div&gt;
  </htmlView>
  <jsonProperties>{"digcompeduSelected":["2.1","2.2","3.1"],
    "digcompeduGranularity":"indicator",
    "digcompeduDataLang":"es",
    "digcompeduSummaryTableHtml":"&lt;table&gt;...&lt;/table&gt;",
    "digcompeduSummaryTextHtml":"&lt;p&gt;...&lt;/p&gt;"}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The DigCompEdu iDevice stores its data as Standard JSON. `digcompeduSelected` is an array of selected indicator IDs (e.g. `"2.1"`, `"3.1"`). `digcompeduGranularity` is either `"indicator"` or `"competence"`. `digcompeduDataLang` selects which framework JSON file to load from `base/digcompedu/data/digcompedu_{lang}.json`. `digcompeduSummaryTableHtml` and `digcompeduSummaryTextHtml` cache the rendered output. No fixture coverage exists in the three test files; this skeleton is derived from the edition JS at `public/files/perm/idevices/base/digcompedu/edition/digcompedu.js:init`.

---

## discover

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215EGCFIE</odePageId>
  <odeBlockId>20251022181215AGEKAQ</odeBlockId>
  <odeIdeviceId>20250605150704RTZIQO</odeIdeviceId>
  <odeIdeviceTypeName>discover</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704RTZIQO",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with discover game data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The discover iDevice uses the URI-encoded JSON in hidden div pattern. The reveal/uncover interaction data (hidden regions and their content) is stored as percent-encoded JSON in a hidden div inside `textTextarea`. The `jsonProperties` object otherwise contains only the standard metadata wrapper keys.

---

## download-source-file

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-manual/content.xml`

```xml
<odeComponent>
  <odePageId>20251027202947OGFWBX</odePageId>
  <odeBlockId>20251027202947OHWSXU</odeBlockId>
  <odeIdeviceId>20251025104201535JS5</odeIdeviceId>
  <odeIdeviceTypeName>download-source-file</odeIdeviceTypeName>
  <htmlView>&lt;div class="exe-download-package-instructions"&gt;
    &lt;table class="exe-table"&gt;
      &lt;caption&gt;Resource metadata&lt;/caption&gt;
      &lt;tbody&gt;
        &lt;tr&gt;&lt;th&gt;Título&lt;/th&gt;&lt;td&gt;Manual de eXeLearning 3.0&lt;/td&gt;&lt;/tr&gt;
        &lt;tr&gt;&lt;th&gt;Descripción&lt;/th&gt;&lt;td&gt;...&lt;/td&gt;&lt;/tr&gt;
        &lt;tr&gt;&lt;th&gt;Autoría&lt;/th&gt;&lt;td&gt;Cedec&lt;/td&gt;&lt;/tr&gt;
        &lt;tr&gt;&lt;th&gt;Licencia&lt;/th&gt;
          &lt;td&gt;&lt;a href="https://creativecommons.org/licenses/by-sa/4.0/"
                 rel="license" class="cc cc-by-sa"&gt;CC BY-SA 4.0&lt;/a&gt;&lt;/td&gt;
        &lt;/tr&gt;
      &lt;/tbody&gt;
    &lt;/table&gt;
    &lt;p&gt;...created with eXeLearning...&lt;/p&gt;
  &lt;/div&gt;
  &lt;p class="exe-download-package-link"&gt;
    &lt;a download="exe-package:elp-name" href="exe-package:elp"
       style="background-color:#0ca1a1;color:#ffffff;"&gt;
      Descargar el archivo .elpx
    &lt;/a&gt;
  &lt;/p&gt;</htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The download-source-file iDevice uses the htmlView-only pattern. It renders a metadata table (title, description, authorship, licence) followed by a download link. The special `href="exe-package:elp"` and `download="exe-package:elp-name"` attributes are resolved by the exporter to the actual `.elpx` filename. All content is encoded directly in `htmlView`; `<jsonProperties/>` is self-closing.

---

## dragdrop

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215VSUXEX</odePageId>
  <odeBlockId>20251022181215FTDJTO</odeBlockId>
  <odeIdeviceId>20250605150704WPLCGC</odeIdeviceId>
  <odeIdeviceTypeName>dragdrop</odeIdeviceTypeName>
  <htmlView>
    <!-- Drag-and-drop activity HTML. Drop zones and draggable items are
         encoded directly in the HTML structure. No jsonProperties store. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The dragdrop iDevice uses the htmlView-only pattern. Drop-target zones and draggable label items are encoded directly in the HTML DOM. `<jsonProperties/>` is self-closing. The `teacherOnly` property is explicitly present in this iDevice's property list.

---

## example

**Storage pattern:** Standard JSON | **Downloadable:** yes

Not present in fixtures — skeleton based on `public/files/perm/idevices/base/example/edition/example.js:getDataJson`.

```xml
<odeComponent>
  <odePageId>YYYYMMDDHHMMSSAAAAAA</odePageId>
  <odeBlockId>YYYYMMDDHHMMSSBBBBBB</odeBlockId>
  <odeIdeviceId>YYYYMMDDHHMMSSCCCCCC</odeIdeviceId>
  <odeIdeviceTypeName>example</odeIdeviceTypeName>
  <htmlView>
    &lt;div class="example-IDevice"&gt;
      &lt;!-- Rendered output from example.html template --&gt;
    &lt;/div&gt;
  </htmlView>
  <jsonProperties>{"text":"Hello world",
    "dataList":"element_1",
    "number":3,
    "color":"#fbbf3c",
    "switch":false,
    "radio":"element_1"}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The example iDevice is a reference implementation for the api-version 3.0 Standard JSON pattern. Its `jsonProperties` keys are `text` (free text), `dataList` (selected option from a predefined list), `number` (integer), `color` (hex color string), `switch` (boolean), and `radio` (selected radio value). This iDevice is `downloadable=1` — the only type in the catalog with that flag set. No fixture coverage; skeleton derived from `public/files/perm/idevices/base/example/edition/example.js`.

---

## external-website

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-manual/content.xml`

```xml
<odeComponent>
  <odePageId>20251027202947APQPMG</odePageId>
  <odeBlockId>20251027202947TJMRCT</odeBlockId>
  <odeIdeviceId>202510211206065735S7</odeIdeviceId>
  <odeIdeviceTypeName>external-website</odeIdeviceTypeName>
  <htmlView>&lt;div id="iframeWebsiteIdevice"&gt;
  &lt;iframe src="https://cedec.intef.es/" size="2"
          width="600" height="300" style="width:100%;"&gt;
  &lt;/iframe&gt;
  &lt;div class="iframe-error-message" style="display:none;"&gt;
    No se puede mostrar un iframe en HTTP en una web HTTPS.
  &lt;/div&gt;
&lt;/div&gt;</htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The external-website iDevice uses the htmlView-only pattern. The URL is embedded in an `<iframe src="...">` inside `htmlView`. The companion `class="iframe-error-message"` div is shown by JavaScript when the page is served over HTTPS but the framed URL is HTTP. `<jsonProperties/>` is self-closing.

---

## flipcards

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215YBLEHR</odePageId>
  <odeBlockId>20251022181215OMIFPO</odeBlockId>
  <odeIdeviceId>20250605150704GCEFQI</odeIdeviceId>
  <odeIdeviceTypeName>flipcards</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704GCEFQI",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with card data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The flipcards (memory cards) iDevice uses the URI-encoded JSON in hidden div pattern. Front/back card content pairs are stored as percent-encoded JSON in a hidden div within `textTextarea`. `jsonProperties` contains only the thin metadata wrapper; `textFeedbackTextarea` carries optional post-activity feedback HTML.

---

## form

**Storage pattern:** Standard JSON | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215JBBARR</odePageId>
  <odeBlockId>20251022181215LJHQGP</odeBlockId>
  <odeIdeviceId>20250605150704YWTQEJ</odeIdeviceId>
  <odeIdeviceTypeName>form</odeIdeviceTypeName>
  <htmlView>
    <!-- Rendered form HTML. Full structure with question divs is omitted;
         all question data is reconstructed at runtime from jsonProperties. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties>{"ideviceId":"20250605150704YWTQEJ",
    "evaluation":true,
    "evaluationID":"987654T",
    "repeatActivity":true,
    "isScorm":1,
    "textButtonScorm":"Guardar puntuación",
    "weighted":100,
    "msgs":{
      "msgCheck":"Comprobar",
      "msgReset":"Reiniciar",
      "msgShowAnswers":"Mostrar respuestas"
    },
    "id":"20250605150704YWTQEJ",
    "questionsRandom":false,
    "percentageQuestions":"100",
    "time":"0",
    "eXeFormInstructions":"&lt;p&gt;Instructions HTML&lt;/p&gt;",
    "questionsData":[
      {"activityType":"true-false","baseText":"&lt;p&gt;Question?&lt;/p&gt;","answer":"1"},
      {"activityType":"selection","selectionType":"single",
       "baseText":"&lt;p&gt;Which?&lt;/p&gt;",
       "answers":[[false,"Wrong"],[true,"Correct"]]},
      {"activityType":"selection","selectionType":"multiple",
       "baseText":"&lt;p&gt;Pick all that apply&lt;/p&gt;",
       "answers":[[true,"A"],[false,"B"],[true,"C"]]}
    ],
    "passRate":5,
    "addBtnAnswers":true,
    "eXeIdeviceTextAfter":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The form iDevice uses Standard JSON. `questionsData` is an array of question objects, each with `activityType` (`"true-false"`, `"selection"`, or `"fill"`), `baseText` (HTML question), and type-specific answer data. For `"selection"` questions, `selectionType` is `"single"` or `"multiple"` and `answers` is an array of `[isCorrect, labelText]` pairs. `evaluation` enables SCORM score tracking; `evaluationID` links to the gradebook entry. `msgs` holds all user-visible button and feedback labels.

---

## geogebra-activity

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215MIQVVZ</odePageId>
  <odeBlockId>20251022181215BGSYII</odeBlockId>
  <odeIdeviceId>20250605150704KCWYSA</odeIdeviceId>
  <odeIdeviceTypeName>geogebra-activity</odeIdeviceTypeName>
  <htmlView>
    <!-- GeoGebra applet embed. The material ID and applet parameters
         are encoded directly in the HTML. No jsonProperties data store. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The geogebra-activity iDevice uses the htmlView-only pattern. The GeoGebra material ID and applet configuration parameters are embedded directly in the `htmlView` HTML. `<jsonProperties/>` is self-closing.

---

## guess

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215TUELCX</odePageId>
  <odeBlockId>20251022181215RTAMMO</odeBlockId>
  <odeIdeviceId>20250605150704CWXHNG</odeIdeviceId>
  <odeIdeviceTypeName>guess</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704CWXHNG",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with guess game data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The guess iDevice (hangman-style letter-guessing game) uses the URI-encoded JSON in hidden div pattern. The word list and clues are stored as percent-encoded JSON in a hidden div inside `textTextarea`. `jsonProperties` carries only the metadata wrapper keys.

---

## hidden-image

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215QCFGOX</odePageId>
  <odeBlockId>20251022181215FUGKLE</odeBlockId>
  <odeIdeviceId>20250605150704EJQUEU</odeIdeviceId>
  <odeIdeviceTypeName>hidden-image</odeIdeviceTypeName>
  <htmlView>
    <!-- Image with a progressively-revealed overlay. The image path,
         overlay grid configuration, and reveal order are embedded
         directly in the HTML. No jsonProperties data store. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The hidden-image iDevice uses the htmlView-only pattern. The image source path and the grid-tile reveal configuration are encoded directly in the `htmlView` HTML structure. `<jsonProperties/>` is self-closing.

---

## identify

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215XHHSMU</odePageId>
  <odeBlockId>20251022181215ACLAEU</odeBlockId>
  <odeIdeviceId>20250605150704VWUSZO</odeIdeviceId>
  <odeIdeviceTypeName>identify</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704VWUSZO",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with identify game data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The identify iDevice (click-on-image hotspot activity) uses the URI-encoded JSON in hidden div pattern. Hotspot coordinates and labels are stored as percent-encoded JSON in a hidden div inside `textTextarea`. `jsonProperties` contains only the metadata wrapper keys.

---

## image-gallery

**Storage pattern:** Standard JSON | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-manual/content.xml`

```xml
<odeComponent>
  <odePageId>20251027202947LOYKIH</odePageId>
  <odeBlockId>20251027202947XBZMTO</odeBlockId>
  <odeIdeviceId>20251023084607814UOH</odeIdeviceId>
  <odeIdeviceTypeName>image-gallery</odeIdeviceTypeName>
  <htmlView>
    &lt;!-- Idevice Example template start --&gt;
    &lt;div class="exe-image-gallery-template"&gt;
      &lt;div class="imageGallery-IDevice"&gt;
        &lt;div class="imageGallery-body"&gt;
          &lt;div id="imageContainer_0" class="imageContainer"&gt;
            &lt;a idevice-id="20251023084607814UOH"
               title="mito común"
               href="{{context_path}}/20251023084607814UOH//1X5A5365.jpg"
               class="imageLink"&gt;
              &lt;div class="imageElement"&gt;
                &lt;img src="{{context_path}}/20251023084607814UOH//1X5A5365_thumb.jpg"
                     height="128" width="128"
                     title="mito común" alt="mito común"
                     author="Pablo Amaya"
                     authorlink="https://www.instagram.com/pabloamayabarbosa/"
                     license="CC-BY-SA"
                     licenselink="http://creativecommons.org/licenses/"/&gt;
              &lt;/div&gt;
            &lt;/a&gt;
          &lt;/div&gt;
          &lt;!-- additional imageContainer_N divs follow the same pattern --&gt;
        &lt;/div&gt;
      &lt;/div&gt;
    &lt;/div&gt;
  </htmlView>
  <jsonProperties>{"ideviceId":"20251023084607814UOH",
    "img_0":{
      "img":"{{context_path}}/20251023084607814UOH//1X5A5365.jpg",
      "thumbnail":"{{context_path}}/20251023084607814UOH//1X5A5365_thumb.jpg",
      "title":"mito común",
      "linktitle":"",
      "author":"Pablo Amaya",
      "linkauthor":"https://www.instagram.com/pabloamayabarbosa/",
      "license":"CC-BY-SA"
    },
    "img_1":{
      "img":"{{context_path}}/20251023084607814UOH//IMG_1913.jpg",
      "thumbnail":"{{context_path}}/20251023084607814UOH//IMG_1913_thumb.jpg",
      "title":"milano negro",
      "linktitle":"",
      "author":"Pablo Amaya",
      "linkauthor":"https://www.instagram.com/pabloamayabarbosa/",
      "license":"CC-BY-SA"
    }
  }
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The image-gallery iDevice uses Standard JSON. Images are stored as numbered keys `img_0`, `img_1`, ..., `img_N` in `jsonProperties`. Each object has `img` (full-size path), `thumbnail` (thumb path), `title`, `linktitle` (optional link URL for the title), `author`, `linkauthor`, and `license`. Paths use the `{{context_path}}/IDEVICEID/FILENAME` template pattern, which the exporter resolves to the actual asset location. Thumbnail filenames follow the convention `BASENAME_thumb.EXT`.

---

## interactive-video

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215SZEJVR</odePageId>
  <odeBlockId>20251022181215JOTXJP</odeBlockId>
  <odeIdeviceId>20250605150704XZJSFI</odeIdeviceId>
  <odeIdeviceTypeName>interactive-video</odeIdeviceTypeName>
  <htmlView>
    <!-- Interactive video player with question overlays at specified
         timestamps. Video URL and question data are encoded directly
         in the HTML. No jsonProperties data store. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The interactive-video iDevice uses the htmlView-only pattern. The video source URL and timestamped question overlays are encoded directly in the `htmlView` HTML. `<jsonProperties/>` is self-closing.

---

## magnifier

**Storage pattern:** Standard JSON | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-manual/content.xml`

```xml
<odeComponent>
  <odePageId>20251027202947VBLZIJ</odePageId>
  <odeBlockId>20251027202947PCBSRS</odeBlockId>
  <odeIdeviceId>2025102112033528604B</odeIdeviceId>
  <odeIdeviceTypeName>magnifier</odeIdeviceTypeName>
  <htmlView>&lt;div class="exe-magnifier-container"&gt;
  &lt;div class="MNF-MainContainer" id="mnfPMainContainer-2025102112033528604B"
       style="display:flex; flex-direction:row; align-items:flex-start;"&gt;
    &lt;div class="MNF-instructions" style="flex:1;"&gt;
      &lt;p&gt;Elige el nivel de aumento y el tamaño de la lupa.&lt;/p&gt;
    &lt;/div&gt;
    &lt;div class="MNF-image-wrapper" id="image-wrapper-2025102112033528604B"&gt;
      &lt;div class="ImageMagnifierIdevice"&gt;
        &lt;div class="image-thumbnail" id="image-thumbnail-2025102112033528604B"&gt;
          &lt;div style="position:relative; display:block; width:400; height:auto;"&gt;
            &lt;img id="magnifier-2025102112033528604B"
                 src="{{context_path}}/2025102112033528604B/myimage.jpg"
                 data-magnifysrc="{{context_path}}/2025102112033528604B/myimage.jpg"
                 width="400"
                 data-size="2"
                 data-zoom="200"&gt;
          &lt;/div&gt;
        &lt;/div&gt;
      &lt;/div&gt;
    &lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</htmlView>
  <jsonProperties>{"id":"2025102112033528604B",
    "typeGame":"magnifier",
    "textTextarea":"&lt;p&gt;Instruction text HTML&lt;/p&gt;",
    "isDefaultImage":"1",
    "imageResource":"",
    "defaultImage":"http://localhost:41309/files/perm/idevices/base/magnifier/edition/hood.jpg",
    "height":"",
    "width":"400",
    "align":"right",
    "initialZSize":"200",
    "maxZSize":600,
    "glassSize":"2",
    "ideviceId":"2025102112033528604B"}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The magnifier iDevice uses Standard JSON. Key fields: `imageResource` is the user-uploaded asset path (empty if using `defaultImage`); `width`/`height` control the display dimensions; `initialZSize` is the initial zoom percentage; `maxZSize` is the maximum zoom; `glassSize` controls the magnifier lens radius (1–3 scale). `isDefaultImage` is `"1"` when using the bundled placeholder image. The `img` element carries `data-zoom` and `data-size` attributes that the magnifier script reads at runtime.

---

## map

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215FFFDXR</odePageId>
  <odeBlockId>20251022181215TOHERQ</odeBlockId>
  <odeIdeviceId>20250605150704RCMMJH</odeIdeviceId>
  <odeIdeviceTypeName>map</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704RCMMJH",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with map markers data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The map iDevice uses the URI-encoded JSON in hidden div pattern. The Leaflet/OpenStreetMap configuration — including centre coordinates, zoom level, and all marker definitions with popup HTML — is stored as percent-encoded JSON in a hidden div inside `textTextarea`. Given that the map data can be very large (over 70 KB for a rich map), this is one of the largest `htmlView` payloads in the fixture set.

---

## mathematicaloperations

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215NHKMBU</odePageId>
  <odeBlockId>20251022181215JDOTYI</odeBlockId>
  <odeIdeviceId>20250605150704MEZACM</odeIdeviceId>
  <odeIdeviceTypeName>mathematicaloperations</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704MEZACM",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with operations data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The mathematicaloperations iDevice uses the URI-encoded JSON in hidden div pattern. Arithmetic operation sets (operands, operators, expected results) are stored as percent-encoded JSON in a hidden div inside `textTextarea`. `jsonProperties` carries only the standard metadata wrapper.

---

## mathproblems

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215NUIQEQ</odePageId>
  <odeBlockId>20251022181215FAMKCN</odeBlockId>
  <odeIdeviceId>20250605150704ZVCKDV</odeIdeviceId>
  <odeIdeviceTypeName>mathproblems</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704ZVCKDV",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with math problems data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The mathproblems iDevice uses the URI-encoded JSON in hidden div pattern. Word problem text, numeric parameters, and answer validation rules are stored as percent-encoded JSON in a hidden div inside `textTextarea`. `jsonProperties` carries only the metadata wrapper.

---

## padlock

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215ZAQUEM</odePageId>
  <odeBlockId>20251022181215EHMYSL</odeBlockId>
  <odeIdeviceId>20250605150704TQZSKC</odeIdeviceId>
  <odeIdeviceTypeName>padlock</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704TQZSKC",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with padlock code data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The padlock iDevice (combination-lock puzzle requiring learners to enter a code unlocked by solving sub-activities) uses the URI-encoded JSON in hidden div pattern. The lock code, hint text, and sub-activity references are stored as percent-encoded JSON in a hidden div inside `textTextarea`.

---

## periodic-table

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215DGWYTQ</odePageId>
  <odeBlockId>20251022181215NSTGVS</odeBlockId>
  <odeIdeviceId>20250605150704QLHEQO</odeIdeviceId>
  <odeIdeviceTypeName>periodic-table</odeIdeviceTypeName>
  <htmlView>
    <!-- Interactive periodic table of elements. All element data,
         highlighting configuration, and display mode are encoded
         directly in the HTML. No jsonProperties data store. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The periodic-table iDevice uses the htmlView-only pattern. The full element dataset, any highlighted elements, and the display configuration are embedded directly in the `htmlView` HTML. `<jsonProperties/>` is self-closing.

---

## progress-report

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215EWDTOA</odePageId>
  <odeBlockId>20251022181215FKXNRG</odeBlockId>
  <odeIdeviceId>20251022200826143PUO</odeIdeviceId>
  <odeIdeviceTypeName>progress-report</odeIdeviceTypeName>
  <htmlView>
    <!-- Aggregate score and completion dashboard. Reads SCORM runtime
         data to display progress across the package. All dashboard
         configuration is embedded in the HTML. No jsonProperties store. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The progress-report iDevice uses the htmlView-only pattern. It renders a SCORM progress dashboard that reads live completion and score data from the SCORM runtime at display time. No editable JSON properties are stored; the entire widget configuration is baked into `htmlView`.

---

## puzzle

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215HNRPFM</odePageId>
  <odeBlockId>20251022181215UIHYZA</odeBlockId>
  <odeIdeviceId>20250605150704FOKAPF</odeIdeviceId>
  <odeIdeviceTypeName>puzzle</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704FOKAPF",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with puzzle image data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The puzzle iDevice uses the URI-encoded JSON in hidden div pattern. The source image path, grid dimensions (rows × columns), and tile order are stored as percent-encoded JSON in a hidden div inside `textTextarea`.

---

## quick-questions

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215SFKZHH</odePageId>
  <odeBlockId>20251022181215DQADOW</odeBlockId>
  <odeIdeviceId>20250605150704UJHZFQ</odeIdeviceId>
  <odeIdeviceTypeName>quick-questions</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704UJHZFQ",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with test questions data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The quick-questions (Test) iDevice uses the URI-encoded JSON in hidden div pattern. Short-answer and true/false questions with their correct answers are stored as percent-encoded JSON in a hidden div inside `textTextarea`. `jsonProperties` carries only the metadata wrapper.

---

## quick-questions-multiple-choice

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215VQFAZW</odePageId>
  <odeBlockId>20251022181215AFDFKE</odeBlockId>
  <odeIdeviceId>20250605150704XZIELR</odeIdeviceId>
  <odeIdeviceTypeName>quick-questions-multiple-choice</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704XZIELR",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with MC questions data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The quick-questions-multiple-choice (Select) iDevice uses the URI-encoded JSON in hidden div pattern. Multiple-choice question definitions — question text, answer options, and correct answer indices — are stored as percent-encoded JSON in a hidden div inside `textTextarea`.

---

## quick-questions-video

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215FZKWXE</odePageId>
  <odeBlockId>20251022181215OZZZNR</odeBlockId>
  <odeIdeviceId>20250605150704YGWXFR</odeIdeviceId>
  <odeIdeviceTypeName>quick-questions-video</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704YGWXFR",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with video test data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The quick-questions-video (Video test) iDevice uses the URI-encoded JSON in hidden div pattern. A video URL, pause timestamps, and per-timestamp question definitions are stored as percent-encoded JSON in a hidden div inside `textTextarea`.

---

## relate

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215ACZURA</odePageId>
  <odeBlockId>20251022181215RLQGVW</odeBlockId>
  <odeIdeviceId>20250605150704BRBLML</odeIdeviceId>
  <odeIdeviceTypeName>relate</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704BRBLML",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with matching pairs data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The relate (matching-pairs) iDevice uses the URI-encoded JSON in hidden div pattern. Left-column and right-column item pairs are stored as percent-encoded JSON in a hidden div inside `textTextarea`.

---

## rubric

**Storage pattern:** htmlView-only | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-manual/content.xml`

```xml
<odeComponent>
  <odePageId>20251027202947HBMUNP</odePageId>
  <odeBlockId>20251027202947GCSDFW</odeBlockId>
  <odeIdeviceId>20251021091936UTBELO</odeIdeviceId>
  <odeIdeviceTypeName>rubric</odeIdeviceTypeName>
  <htmlView>&lt;table class="exe-table"&gt;
  &lt;caption&gt;Rúbrica para evaluar un trabajo escrito&lt;/caption&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;&amp;nbsp;&lt;/th&gt;
      &lt;th&gt;4 Excelente&lt;/th&gt;
      &lt;th&gt;3 Satisfactorio&lt;/th&gt;
      &lt;th&gt;2 Mejorable&lt;/th&gt;
      &lt;th&gt;1 Insuficiente&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;th&gt;Aspectos formales&lt;/th&gt;
      &lt;td&gt;Cumple todos los aspectos. &lt;span&gt;(4)&lt;/span&gt;&lt;/td&gt;
      &lt;td&gt;Cumple casi todos. &lt;span&gt;(3)&lt;/span&gt;&lt;/td&gt;
      &lt;td&gt;Cumple algunos. &lt;span&gt;(2)&lt;/span&gt;&lt;/td&gt;
      &lt;td&gt;No cumple. &lt;span&gt;(1)&lt;/span&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;!-- additional criterion rows follow the same pattern --&gt;
  &lt;/tbody&gt;
&lt;/table&gt;
&lt;p class="exe-rubrics-authorship"&gt;
  &lt;a href="http://cedec.intef.es/" class="author"&gt;CEDEC&lt;/a&gt;.
  &lt;span class="title"&gt;&lt;em&gt;Rubric title&lt;/em&gt;&lt;/span&gt;
  &lt;span class="license"&gt;(&lt;a href="..." rel="license"&gt;CC BY-SA&lt;/a&gt;)&lt;/span&gt;
&lt;/p&gt;
&lt;ul class="exe-rubrics-strings"&gt;
  &lt;li class="activity"&gt;Actividad&lt;/li&gt;
  &lt;li class="name"&gt;Nombre&lt;/li&gt;
  &lt;li class="date"&gt;Fecha&lt;/li&gt;
  &lt;li class="score"&gt;Puntuación&lt;/li&gt;
  &lt;li class="notes"&gt;Notas&lt;/li&gt;
  &lt;li class="reset"&gt;Reiniciar&lt;/li&gt;
  &lt;li class="print"&gt;Imprimir&lt;/li&gt;
&lt;/ul&gt;</htmlView>
  <jsonProperties/>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The rubric iDevice uses the htmlView-only pattern. The entire assessment grid is stored as an HTML table; `<jsonProperties/>` is self-closing. The `class="exe-rubrics-strings"` `<ul>` element carries localised label strings (activity, name, date, score, notes, reset, print) that the rubric JavaScript reads at runtime to populate the printable evaluation form.

---

## scrambled-list

**Storage pattern:** Standard JSON | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215ARMDHO</odePageId>
  <odeBlockId>20251022181215ZTHBCN</odeBlockId>
  <odeIdeviceId>20250605150704CJUQLN</odeIdeviceId>
  <odeIdeviceTypeName>scrambled-list</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"typeGame":"ScrambledList",
    "instructions":"&lt;p&gt;Sort the items into the correct order&lt;/p&gt;",
    "textAfter":"",
    "afterElement":"",
    "options":["First item","Second item","Third item"],
    "time":0,
    "buttonText":"Comprobar",
    "rightText":"¡Correcto!",
    "wrongText":"Inténtalo de nuevo",
    "isScorm":1,
    "textButtonScorm":"Guardar puntuación",
    "repeatActivity":true,
    "weighted":100,
    "evaluation":true,
    "evaluationID":"987654T",
    "ideviceId":"20250605150704CJUQLN"}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The scrambled-list iDevice is notable for using the api-version 3.0 Standard JSON pattern even though it is categorised as an interactive activity. `options` is an ordered array of strings representing the correct sequence (the editor scrambles them for display). `instructions` is rich-text HTML. `time` is a per-item time limit in seconds (0 = unlimited). `rightText`/`wrongText` are feedback labels. `evaluation` + `evaluationID` enable SCORM score tracking.

---

## select-media-files

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215NQHJFI</odePageId>
  <odeBlockId>20251022181215HRTVWF</odeBlockId>
  <odeIdeviceId>20250605150704KZYGBR</odeIdeviceId>
  <odeIdeviceTypeName>select-media-files</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704KZYGBR",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with media selection data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The select-media-files iDevice uses the URI-encoded JSON in hidden div pattern. The list of media items (images or audio clips) from which the learner must select the correct answer is stored as percent-encoded JSON in a hidden div inside `textTextarea`.

---

## sort

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215WAYWUV</odePageId>
  <odeBlockId>20251022181215XVBSYN</odeBlockId>
  <odeIdeviceId>20250605150704WQAZQP</odeIdeviceId>
  <odeIdeviceTypeName>sort</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704WQAZQP",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with sort activity data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The sort iDevice uses the URI-encoded JSON in hidden div pattern. Items to be placed in chronological or logical order, together with their correct sequence indices, are stored as percent-encoded JSON in a hidden div inside `textTextarea`.

---

## text

**Storage pattern:** Standard JSON | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-manual/content.xml`

```xml
<odeComponent>
  <odePageId>20251027202947MKIISA</odePageId>
  <odeBlockId>20251027202947EDIAYV</odeBlockId>
  <odeIdeviceId>20251025070914XDRVFP</odeIdeviceId>
  <odeIdeviceTypeName>text</odeIdeviceTypeName>
  <htmlView>&lt;div class="exe-text-template"&gt;
  &lt;div class="textIdeviceContent"&gt;
    &lt;div class="exe-text-activity"&gt;
      &lt;div&gt;
        &lt;div class="exe-text"&gt;
          &lt;h1 style="text-align:center;"&gt;Manual de eXeLearning 3.0&lt;/h1&gt;
          &lt;p&gt;&lt;img src="{{context_path}}/20251025070914XDRVFP/logo.png"
                   width="342" height="309" alt="logo exe"
                   style="display:block; margin-left:auto; margin-right:auto;"&gt;&lt;/p&gt;
          &lt;p style="text-align:center;"&gt;Guía práctica...&lt;/p&gt;
        &lt;/div&gt;
        &lt;p class="clearfix"&gt;&lt;/p&gt;
      &lt;/div&gt;
    &lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</htmlView>
  <jsonProperties>{"ideviceId":"20251025070914XDRVFP",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"&lt;div class=\"exe-text\"&gt;\n&lt;h1&gt;...&lt;/h1&gt;\n...&lt;/div&gt;",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The text iDevice uses Standard JSON. `textTextarea` is the primary content field and contains the rich-text HTML wrapped in `<div class="exe-text">`. Image paths within the HTML use the `{{context_path}}/IDEVICEID/FILENAME` template. `textFeedbackTextarea` holds optional collapsible feedback HTML. `textInfoDurationInput` and `textInfoParticipantsInput` are optional lesson-metadata values rendered as a definition list above the main content when non-empty.

---

## trivial

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215YFOJCC</odePageId>
  <odeBlockId>20251022181215DWGNCI</odeBlockId>
  <odeIdeviceId>20250605150704UZELMR</odeIdeviceId>
  <odeIdeviceTypeName>trivial</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704UZELMR",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with trivial game data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The trivial (TriviExt) iDevice uses the URI-encoded JSON in hidden div pattern. Question categories, question text, answer options, and correct answer indices are stored as percent-encoded JSON in a hidden div inside `textTextarea`.

---

## trueorfalse

**Storage pattern:** Standard JSON | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215YMBLFO</odePageId>
  <odeBlockId>20251022181215BQSJQR</odeBlockId>
  <odeIdeviceId>20250605150704MFDSBR</odeIdeviceId>
  <odeIdeviceTypeName>trueorfalse</odeIdeviceTypeName>
  <htmlView>
    <!-- Pre-rendered True-or-False game. The game scaffold HTML is
         included; question data is in jsonProperties.questionsGame. -->
    ... (htmlView content trimmed for readability) ...
  </htmlView>
  <jsonProperties>{"id":"20250605150704MFDSBR",
    "typeGame":"TrueOrFalse",
    "eXeGameInstructions":"&lt;p&gt;Revisión Final&lt;/p&gt;",
    "eXeIdeviceTextAfter":"",
    "msgs":{
      "msgStartGame":"Haz clic aquí para empezar",
      "msgTrue":"Verdadero",
      "msgFalse":"Falso",
      "msgOk":"Correcto",
      "msgKO":"Incorrecto",
      "msgCheck":"Comprobar",
      "msgReboot":"Inténtalo de nuevo",
      "msgScore":"Puntuación"
    },
    "questionsRandom":false,
    "percentageQuestions":50,
    "isTest":true,
    "time":0,
    "questionsGame":[
      {
        "question":"&lt;p&gt;¿Las plantas realizan la fotosíntesis durante la noche?&lt;/p&gt;",
        "feedback":"&lt;p&gt;La fotosíntesis requiere energía luminosa.&lt;/p&gt;",
        "suggestion":"&lt;p&gt;Reflexiona sobre la necesidad de la luz solar.&lt;/p&gt;",
        "solution":0
      },
      {
        "question":"&lt;p&gt;¿Los metales son buenos conductores de electricidad?&lt;/p&gt;",
        "feedback":"&lt;p&gt;Su estructura atómica permite el libre movimiento de electrones.&lt;/p&gt;",
        "suggestion":"&lt;p&gt;Piensa en los materiales usados en cables eléctricos.&lt;/p&gt;",
        "solution":1
      }
    ],
    "isScorm":1,
    "textButtonScorm":"Guardar puntuación",
    "repeatActivity":true,
    "weighted":100,
    "evaluation":true,
    "evaluationID":"987654T",
    "ideviceId":"20250605150704MFDSBR"}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The trueorfalse iDevice uses Standard JSON. `questionsGame` is an array of question objects each having `question` (HTML), `feedback` (HTML shown after answer), `suggestion` (hint HTML), and `solution` (0 = false, 1 = true). `percentageQuestions` controls how many questions are drawn from the pool per session. `time` is a per-question timer in seconds (0 = unlimited). `msgs` carries all user-visible string labels, enabling full localisation. `evaluation` + `evaluationID` activate SCORM score submission.

---

## udl-content

**Storage pattern:** Standard JSON | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-manual/content.xml`

```xml
<odeComponent>
  <odePageId>20251027202947XQHCJW</odePageId>
  <odeBlockId>20251027202947RLIQTV</odeBlockId>
  <odeIdeviceId>20251021091936QALZGN</odeIdeviceId>
  <odeIdeviceTypeName>udl-content</odeIdeviceTypeName>
  <htmlView>&lt;div class="exe-udlContent exe-udlContent-engagement"&gt;
  &lt;section class="exe-udlContent-block"&gt;
    &lt;div class="exe-udlContent-content"&gt;
      &lt;div class="exe-udlContent-content-main"&gt;
        &lt;h2&gt;Apoyos al contenido principal&lt;/h2&gt;
        &lt;p&gt;7 Razones para usar Software Libre...&lt;/p&gt;
      &lt;/div&gt;
      &lt;article class="exe-udlContent-content-audio js-hidden"&gt;
        &lt;header class="exe-udlContent-alt-content-title"&gt;&lt;h2&gt;Audio&lt;/h2&gt;&lt;/header&gt;
        &lt;audio controls="controls"
               src="{{context_path}}/20251021091936QALZGN/audio.webm"&gt;
        &lt;/audio&gt;
        &lt;button class="exe-udlContent-alt-content-hide"&gt;Cerrar&lt;/button&gt;
      &lt;/article&gt;
      &lt;article class="exe-udlContent-content-visual js-hidden"&gt;
        &lt;header class="exe-udlContent-alt-content-title"&gt;&lt;h2&gt;Apoyo visual&lt;/h2&gt;&lt;/header&gt;
        &lt;img src="{{context_path}}/20251021091936QALZGN/infographic.png"
             alt="infografía" width="600" height="424"&gt;
        &lt;button class="exe-udlContent-alt-content-hide"&gt;Cerrar&lt;/button&gt;
      &lt;/article&gt;
    &lt;/div&gt;
  &lt;/section&gt;
&lt;/div&gt;</htmlView>
  <jsonProperties>{"ideviceId":"20251021091936QALZGN",
    "textInfoDurationInput":"",
    "textInfoParticipantsInput":"",
    "textInfoDurationTextInput":"",
    "textInfoParticipantsTextInput":"",
    "textTextarea":"... (full UDL HTML including main, audio, and visual sections) ...",
    "textFeedbackInput":"",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>teacherOnly</key><value>false</value></odeComponentsProperty>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The udl-content (UDL Content) iDevice uses Standard JSON. `textTextarea` stores the full UDL block HTML including all three representation layers: `exe-udlContent-content-main` (primary text), `exe-udlContent-content-audio` (audio alternative), and `exe-udlContent-content-visual` (visual alternative). The outer div class `exe-udlContent-engagement` / `-representation` / `-action` encodes the UDL principle. Alternative sections are hidden by default (`js-hidden`) and toggled by the UDL navigation buttons rendered by the export template.

---

## word-search

**Storage pattern:** URI-encoded JSON in hidden div | **Downloadable:** no

Source: `/tmp/elpx-docs-work/fix-todos/content.xml`

```xml
<odeComponent>
  <odePageId>20251022181215PCJNMN</odePageId>
  <odeBlockId>20251022181215NOITNZ</odeBlockId>
  <odeIdeviceId>20250605150704YZXLPV</odeIdeviceId>
  <odeIdeviceTypeName>word-search</odeIdeviceTypeName>
  <htmlView>... (htmlView content trimmed for readability) ...</htmlView>
  <jsonProperties>{"ideviceId":"20250605150704YZXLPV",
    "textInfoDurationInput":"",
    "textInfoDurationTextInput":"Duración",
    "textInfoParticipantsInput":"",
    "textInfoParticipantsTextInput":"Agrupamiento",
    "textTextarea":"... (full iDevice HTML with word-search grid data) ...",
    "textFeedbackInput":"Mostrar retroalimentación",
    "textFeedbackTextarea":""}
  </jsonProperties>
  <odeComponentsOrder>1</odeComponentsOrder>
  <odeComponentsProperties>
    <odeComponentsProperty><key>identifier</key><value/></odeComponentsProperty>
    <odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty>
    <odeComponentsProperty><key>cssClass</key><value/></odeComponentsProperty>
  </odeComponentsProperties>
</odeComponent>
```

The word-search iDevice uses the URI-encoded JSON in hidden div pattern. The letter grid, word list, and direction configuration are stored as percent-encoded JSON in a hidden div inside `textTextarea`. `jsonProperties` carries only the metadata wrapper keys.

---

## See also

- [`catalog.md`](catalog.md) — master table of all iDevice types with categories, downloadable flags, api-version, and legacy import aliases
- [`patterns.md`](patterns.md) — detailed explanation of the four storage patterns (Standard JSON, URI-encoded JSON in hidden div, htmlView-only, embedded script JSON)
- [`config-xml.md`](config-xml.md) — schema reference for the per-iDevice `config.xml` metadata file
- [`../content-xml.md`](../content-xml.md) — top-level `content.xml` structure: pages, blocks, and the `<odeComponents>` container that holds these `<odeComponent>` elements


# ===== doc/elpx-format/themes.md =====

# Themes in ELPX Packages

This document describes how themes are bundled inside `.elpx` files: the directory layout, the `config.xml` element reference, the six in-tree themes, fallback behaviour, custom theme portability, and where to find the authoring guide.

> **See also**: [ELPX Format hub](../elpx-format.md) | [Libraries](libraries.md) | [Assets](assets.md) | [Screenshot](screenshot.md) | [Theme authoring guide](../development/styles.md)

---

## 1. Theme bundle layout inside the ZIP

Every exported `.elpx` (and plain HTML5 `.zip`) places the active theme under a top-level `theme/` directory. The layout mirrors the in-tree source directory at `public/files/perm/themes/base/<name>/`.

```
project.elpx (ZIP)
└── theme/
    ├── config.xml          # Theme metadata (name, version, author, …)
    ├── style.css           # Theme stylesheet
    ├── style.js            # Theme JavaScript (navigation, interactions)
    ├── screenshot.png      # THEME preview thumbnail (not the project thumbnail)
    ├── icons/              # iDevice category icons (PNG, one per category)
    │   ├── activity.png
    │   ├── alert.png
    │   └── …
    └── img/                # Theme-specific images (sprites, decorations)
        ├── icons.png
        └── licenses.gif
```

Verified against the unzipped sample at `/tmp/elpx-docs-work/fix-simple/theme/`:

```
theme/config.xml
theme/style.css
theme/style.js
theme/screenshot.png
theme/icons/activity.png
theme/icons/agreement.png
… (48 icon files)
theme/img/icons.png
theme/img/licenses.gif
```

### Distinction: theme screenshot vs. project screenshot

`theme/screenshot.png` is the **theme's own preview image** — used in the eXeLearning UI to show what the theme looks like. It travels with the theme bundle so the importer can display a preview even before the user opens the project.

The project-level `screenshot.png` at the **ZIP root** is the **project thumbnail** (a 1280×720 preview of the actual content). These are two different files with different purposes. See [screenshot.md](screenshot.md) for the project thumbnail specification.

---

## 2. `config.xml` element reference

Each theme directory contains a `config.xml` that declares its identity and licensing terms. The file is valid XML 1.0.

Annotated example — `public/files/perm/themes/base/base/config.xml`:

```xml
<?xml version="1.0"?>
<theme>
    <!-- Internal identifier; must match the directory name -->
    <name>base</name>

    <!-- Human-readable display name shown in the UI -->
    <title>Default</title>

    <!-- Release year / version tag -->
    <version>2025</version>

    <!-- Minimum eXeLearning version required to use this theme -->
    <compatibility>3.0</compatibility>

    <!-- Theme author(s) -->
    <author>eXeLearning.net</author>

    <!-- SPDX-compatible licence name -->
    <license>Creative Commons by-sa</license>

    <!-- Canonical licence URL -->
    <license-url>http://creativecommons.org/licenses/by-sa/3.0/</license-url>

    <!-- Free-text description shown in the theme picker -->
    <description>Minimally-styled, feature rich responsive style for eXe.

iDevice icons by Francisco Javier Pulido Cuadrado.</description>

    <!-- 1 = available for download from the theme repository; 0 = internal only -->
    <downloadable>1</downloadable>
</theme>
```

### Element reference table

| Element | Required | Description |
|---------|----------|-------------|
| `<name>` | Yes | Unique machine identifier. Must equal the containing directory name. Used by `OdeXmlGenerator` and `Html5Exporter` to look up the theme. |
| `<title>` | Yes | Localised display name in the theme picker. |
| `<version>` | Yes | Version string; current in-tree themes use the four-digit year. No strict format enforced. |
| `<compatibility>` | Yes | Minimum eXeLearning version. The exporter uses `3.0` for all current themes. |
| `<author>` | Yes | Attribution text. May include multiple contributors. |
| `<license>` | Yes | Licence short name. |
| `<license-url>` | Yes | Full URL to the licence text. |
| `<description>` | Yes | Multi-line description. May include font and icon attribution. |
| `<downloadable>` | Yes | `1` if users can install the theme from the online repository; `0` for internal/dev themes. |

---

## 3. The six in-tree themes

All six themes ship in `public/files/perm/themes/base/`. Data read from each `config.xml`:

| `name` | `title` | `version` | `compatibility` | `downloadable` | One-line description |
|--------|---------|-----------|-----------------|----------------|----------------------|
| `base` | Default | 2025 | 3.0 | 1 | Minimally-styled, feature-rich responsive theme. iDevice icons by F.J. Pulido. |
| `flux` | Flux | 2025 | 3.0 | 1 | "Energía en movimiento." Fredoka font, Google Material icons. By 3ipunt / Consejería Ed. Canarias. |
| `neo` | Neo | 2025 | 3.0 | 1 | "Innovación con propósito." Nunito font. By 3ipunt for eXeLearning.net. |
| `nova` | Nova | 2025 | 3.0 | 1 | "Aprender, crecer, avanzar." Open Sans font. By 3ipunt / Consejería Ed. Canarias. |
| `universal` | Universal | 2025 | 3.0 | 1 | Accessibility-focused (UDL). Atkinson Hyperlegible font. By Ignacio Gros for EducaMadrid. |
| `zen` | Zen | 2025 | 3.0 | 1 | "Equilibrio y claridad." Inter font, Google Material icons. By 3ipunt for eXeLearning.net. |

---

## 4. Default theme fallback

When no theme is specified (or the project's `meta.theme` field is empty), the exporter falls back to `base`.

This is written in two places:

**`src/shared/export/generators/OdeXmlGenerator.ts:79`** — `content.xml` always records a theme:

```typescript
xml += generateUserPreferenceEntry('theme', meta.theme || 'base');
```

**`src/shared/export/exporters/Html5Exporter.ts:76`** — the HTML5 exporter resolves the theme name before fetching theme files:

```typescript
const themeName = html5Options?.theme || meta.theme || 'base';
```

Priority order: (1) export option parameter, (2) project metadata, (3) hard-coded `'base'`.

If `prepareThemeData(themeName)` fails to find the requested theme (for example, a custom theme that is missing from the resource cache), `Html5Exporter` falls back to inline CSS/JS stubs via `getFallbackThemeCss()` and `getFallbackThemeJs()` (`Html5Exporter.ts:261–265`):

```typescript
} else {
    // Add fallback theme if pre-fetch failed
    addFile('theme/style.css', this.getFallbackThemeCss());
    addFile('theme/style.js', this.getFallbackThemeJs());
}
```

The fallback produces a minimal, unstyled layout so the exported content remains readable even when the preferred theme cannot be resolved.

---

## 5. Custom user themes

Custom themes created or installed by the user are **not** stored on the server filesystem at export time. They live in the browser's IndexedDB resources cache (`exelearning-resources-v1`).

When a project that uses a custom theme is exported:

1. `Html5Exporter.prepareThemeData(themeName)` fetches the theme files from the resource layer (`this.resources`), which is backed by IndexedDB in the browser and by the filesystem in server-side / CLI exports.
2. All theme files (`style.css`, `style.js`, `config.xml`, `screenshot.png`, `icons/`, `img/`) are iterated from `themeFilesMap` and added to the ZIP under `theme/` (`Html5Exporter.ts:256–265`):

```typescript
if (themeFilesMap) {
    for (const [filePath, content] of themeFilesMap) {
        addFile(`theme/${filePath}`, content);
    }
}
```

This makes the package **self-contained**: recipients can view the content in a browser or re-import it into eXeLearning without needing to install the custom theme separately. The theme is fully embedded in the `.elpx`.

On import, `ElpxImporter` reads the theme name from `content.xml` and stores it in the Yjs `metadata` map. The theme files themselves are not extracted back to IndexedDB during import; the importer relies on the embedded HTML output already referencing `theme/style.css` and `theme/style.js` with correct relative paths.

---

## 6. Authoring a new theme

Creating a custom theme involves writing `style.css`, `style.js`, and the supporting files described in section 1.

Full authoring instructions, SCSS compilation steps, and the variable reference are in the dedicated guide:

**[doc/development/styles.md](../development/styles.md)**

This document does not duplicate that content. Refer to `styles.md` for:

- SCSS architecture and variable overrides
- How to register a new theme in the development environment
- Hot-reload workflow during authoring
- Accessibility requirements

---

## 7. Relationship between exported `theme/` and source `public/files/perm/themes/base/<name>/`

The directory structures are identical. The export process copies every file from the source theme directory into the ZIP `theme/` prefix without transformation. There is no build step applied to theme CSS or JS at export time — the files in `public/files/perm/themes/base/<name>/` are already the final production assets.

```
Source:  public/files/perm/themes/base/base/style.css
ZIP:     theme/style.css

Source:  public/files/perm/themes/base/base/icons/activity.png
ZIP:     theme/icons/activity.png
```

Custom themes follow the same convention: wherever the resource layer stores the theme files, they are mapped 1:1 into the `theme/` subtree in the ZIP.


# ===== doc/elpx-format/libraries.md =====

# Libraries in ELPX Packages

This document describes the JavaScript and CSS libraries bundled under `libs/` in every `.elpx` export: which files are always present, which are added conditionally based on content, and where each file originates.

> **See also**: [ELPX Format hub](../elpx-format.md) | [Themes](themes.md) | [Assets](assets.md) | [Screenshot](screenshot.md)

---

## 1. `libs/` directory inventory

The following listing is taken from the unzipped sample at `/tmp/elpx-docs-work/fix-simple/libs/`:

```
libs/
├── bootstrap/
│   ├── bootstrap.bundle.min.js
│   ├── bootstrap.bundle.min.js.map
│   ├── bootstrap.min.css
│   └── bootstrap.min.css.map
├── exe_atools/
│   ├── exe_atools.css
│   ├── exe_atools.js
│   ├── exe_atools.png          (sprite sheet)
│   ├── exe_atools_ah.woff2
│   ├── exe_atools_ah_ext.woff2
│   ├── exe_atools_mo.woff2
│   ├── exe_atools_mo_cy.woff2
│   ├── exe_atools_mo_cy_ext.woff2
│   ├── exe_atools_mo_ext.woff2
│   └── exe_atools_mo_vi.woff2
├── jquery/
│   └── jquery.min.js
├── common.js
├── common_i18n.js
├── exe_export.js
└── favicon.ico
```

This sample uses only the `text` iDevice, so no iDevice-specific or conditional libraries appear. When additional iDevices or features are used, more subdirectories are added (see section 3).

---

## 2. Always-bundled base libraries

The constant `BASE_LIBRARIES` in `src/shared/export/constants.ts:325` defines the set of files fetched unconditionally for every export:

```typescript
export const BASE_LIBRARIES = [
    'jquery/jquery.min.js',
    'common.js',
    'exe_export.js',
    'bootstrap/bootstrap.bundle.min.js',
    'bootstrap/bootstrap.bundle.min.js.map',
    'bootstrap/bootstrap.min.css',
    'bootstrap/bootstrap.min.css.map',
];
```

`Html5Exporter` fetches this set at step 7 (`Html5Exporter.ts:267–275`):

```typescript
const baseLibs = await this.resources.fetchBaseLibraries();
for (const [libPath, content] of baseLibs) {
    addFile(`libs/${libPath}`, content);
}
```

Two additional files are always generated or copied outside the `BASE_LIBRARIES` constant:

- **`libs/common_i18n.js`** — generated per-export by `generateI18nContent(meta.language)` (step 7.5, `Html5Exporter.ts:278`). It is a JavaScript file containing localised UI strings (navigation labels, button text) for the content language. It is never a static file; it is produced fresh for each export from the translation tables.
- **`libs/favicon.ico`** — the eXeLearning favicon. Included as part of the base library set fetched from the resource layer.

---

## 3. Conditionally-bundled libraries

Additional libraries are included only when the exported content requires them. Detection is performed by `LibraryDetector.getAllRequiredFilesWithPatternsFromFragments()`, called at step 8 of the HTML5 export (`Html5Exporter.ts:285`):

```typescript
const { files: allRequiredFiles, patterns } = this.getRequiredLibraryFilesForPages(pages, {
    includeAccessibilityToolbar: meta.addAccessibilityToolbar === true,
    includeMathJax: meta.addMathJax === true,
    skipMathJax: latexWasRendered && !meta.addMathJax,
});
```

`getRequiredLibraryFilesForPages` is defined in `BaseExporter.ts:943`. It delegates to `LibraryDetector`, which scans every HTML fragment from every iDevice across all pages and matches against `LIBRARY_PATTERNS` (`src/shared/export/constants.ts:107`).

### 3.1 Conditional library matrix

| Library name | Trigger condition | Files added under `libs/` |
|---|---|---|
| `exe_effects` | Content contains a `exe-effects` CSS class | `exe_effects/exe_effects.js` |
| `exe_games` | Content contains a `exe-games` CSS class | `exe_games/exe_games.js`, CSS |
| `exe_highlighter` | Content contains `exe-highlighter` class | `exe_highlighter/exe_highlighter.js`, CSS |
| `exe_lightbox` | Single image with lightbox enabled | `exe_lightbox/exe_lightbox.js`, `exe_lightbox/exe_lightbox.css` |
| `exe_lightbox_gallery` | Image gallery iDevice | `exe_lightbox/exe_lightbox.js`, `exe_lightbox/exe_lightbox.css` |
| `exe_tooltips` | Tooltips iDevice | `exe_tooltips/jquery.qtip.min.js`, `exe_tooltips/jquery.qtip.min.css` |
| `exe_magnify` | Image magnifier iDevice | `exe_magnify/exe_magnify.js`, CSS |
| `exe_media` | Embedded media (audio/video) iDevice | `exe_media/exe_media.js`, CSS |
| `exe_media_link` | Linked media iDevice | `exe_media_link/exe_media_link.js` |
| `abcjs` | ABC music notation iDevice | `abcjs/abcjs-basic.js` |
| `exe_math` | MathJax LaTeX expressions in content **or** `meta.addMathJax === true` | Entire `exe_math/` directory (dynamic extension loading) |
| `exe_math_datagame` | LaTeX found inside encrypted DataGame div | `exe_math/` directory |
| `exe_math_mathml` | MathML content detected | `exe_math/` directory |
| `exe_atools` | `meta.addAccessibilityToolbar === true` | `exe_atools/exe_atools.js`, `exe_atools/exe_atools.css`, fonts, sprite |
| `exe_elpx_download` | `download-source-file` iDevice (CSS class `exe-download-package-link`) | `fflate/fflate.umd.js`, `exe_elpx_download/exe_elpx_download.js` |
| `exe_elpx_download_protocol` | `exe-package:elp` protocol link in any iDevice | `fflate/fflate.umd.js`, `exe_elpx_download/exe_elpx_download.js` |
| `jquery_ui_*` | Various drag-and-drop/ordering game iDevices | `jquery-ui/jquery-ui.min.js` |

**Notes:**

- **Mermaid** (`mermaid.min.js`) is **never** bundled. Mermaid diagrams are always pre-rendered to static SVG before export (`Html5Exporter.ts:182–196`), eliminating the ~2.7 MB runtime library. The comment at `constants.ts:254` confirms: "Mermaid diagrams are always pre-rendered to static SVG … so the ~2.7MB mermaid.min.js library is never needed."
- **MathJax** (`exe_math/`) is skipped when LaTeX has been pre-rendered to SVG+MathML by the browser hook, unless `meta.addMathJax` is explicitly `true` (`Html5Exporter.ts:288`).
- `exe_atools` contains the accessibility toolbar (font switcher, contrast modes, reading ruler). It is only included when the project's "Add Accessibility Toolbar" option is enabled.

### 3.2 `elpx-manifest.js`

When any page uses the `download-source-file` iDevice or contains an `exe-package:elp` link, the exporter generates a manifest file listing every file in the ZIP (`Html5Exporter.ts:344–350`):

```typescript
if (needsElpxDownload && fileList) {
    fileList.push('libs/elpx-manifest.js');
    const manifestJs = this.generateElpxManifestFile(fileList);
    this.zip.addFile('libs/elpx-manifest.js', manifestJs);
}
```

`elpx-manifest.js` is a generated JavaScript file, not a static resource. It contains the complete list of ZIP entry paths so that the browser-side `exe_elpx_download` library can reconstruct the package on the client without a server round-trip.

---

## 4. `common_i18n.js` generation

`common_i18n.js` is the only library file that is always **generated**, never copied. It is produced at step 7.5 by `generateI18nContent(meta.language || 'en')` (`Html5Exporter.ts:278`):

```typescript
const i18nContent = await this.generateI18nContent(meta.language || 'en');
addFile('libs/common_i18n.js', new TextEncoder().encode(i18nContent));
```

The file contains a JSON-like JavaScript object with localised strings for navigation buttons ("Previous", "Next", "Home"), ARIA labels, and other UI text. The content language stored in `meta.language` (an ISO 639-1 code such as `en`, `es`, `fr`) determines which translation strings are embedded.

---

## 5. Per-iDevice files (`idevices/`)

Each iDevice type that appears in the project may contribute its own CSS and JavaScript. These files are placed under `idevices/<type>/`, **not** under `libs/`. The `libs/` directory is reserved for shared cross-project libraries.

Example:

```
idevices/
└── text/
    ├── text.css
    ├── text.html   (template, used during export rendering)
    └── text.js
```

`Html5Exporter` fetches iDevice resources at step 9 (`Html5Exporter.ts:309–321`):

```typescript
const usedIdevices = this.getUsedIdevices(pages);
for (const idevice of usedIdevices) {
    const normalizedType = this.resources.normalizeIdeviceType(idevice);
    const ideviceFiles = await this.resources.fetchIdeviceResources(idevice);
    for (const [filePath, content] of ideviceFiles) {
        addFile(`idevices/${normalizedType}/${filePath}`, content);
    }
}
```

`getUsedIdevices(pages)` returns the set of distinct iDevice type names found across all pages. Each type name is normalised (e.g. `FreeTextIdevice` → `text`) before forming the ZIP path.

For the iDevice `config.xml` schema and type-name conventions see the iDevice documentation at [doc/elpx-format/idevices/config-xml.md](idevices/config-xml.md).

---

## 6. File-by-file summary

| File | Source location | When included | Purpose |
|------|----------------|---------------|---------|
| `jquery/jquery.min.js` | `public/libs/jquery/` | Always | DOM manipulation framework required by Bootstrap and many iDevices |
| `bootstrap/bootstrap.bundle.min.js` | `public/libs/bootstrap/` | Always | Responsive UI components (modals, dropdowns, accordion) |
| `bootstrap/bootstrap.min.css` | `public/libs/bootstrap/` | Always | Bootstrap base styles |
| `bootstrap/*.map` | `public/libs/bootstrap/` | Always | Source maps for debugging |
| `common.js` | `public/libs/` | Always | eXeLearning shared runtime (navigation, event wiring) |
| `exe_export.js` | `public/libs/` | Always | Export-mode initialisation and SCORM/LMS bridge stubs |
| `favicon.ico` | `public/libs/` | Always | eXeLearning favicon |
| `common_i18n.js` | Generated at export time | Always | Localised UI strings for the content language |
| `exe_atools/exe_atools.js` | `public/libs/exe_atools/` | Accessibility toolbar enabled | Accessibility toolbar (font, contrast, ruler) |
| `exe_atools/exe_atools.css` | `public/libs/exe_atools/` | Accessibility toolbar enabled | Accessibility toolbar styles |
| `exe_atools/*.woff2` / `.woff` | `public/libs/exe_atools/` | Accessibility toolbar enabled | OpenDyslexic and accessible font families |
| `exe_atools/exe_atools.png` | `public/libs/exe_atools/` | Accessibility toolbar enabled | Icon sprite sheet |
| `exe_lightbox/exe_lightbox.js` | `public/libs/exe_lightbox/` | Lightbox or gallery iDevice present | Image lightbox overlay |
| `exe_lightbox/exe_lightbox.css` | `public/libs/exe_lightbox/` | Lightbox or gallery iDevice present | Lightbox styles |
| `exe_math/` (directory) | `public/libs/exe_math/` | MathJax option on, LaTeX detected, or MathML detected | MathJax runtime for LaTeX/MathML rendering |
| `fflate/fflate.umd.js` | `public/libs/fflate/` | download-source-file iDevice present | Client-side ZIP generation library |
| `exe_elpx_download/exe_elpx_download.js` | `public/libs/exe_elpx_download/` | download-source-file iDevice present | Client-side ELPX package assembly |
| `libs/elpx-manifest.js` | Generated at export time | download-source-file iDevice present | Full file manifest for client-side ZIP reconstruction |
| `jquery-ui/jquery-ui.min.js` | `public/libs/jquery-ui/` | Ordering/sorting/drag-drop game iDevices | jQuery UI interactions |
| `exe_tooltips/jquery.qtip.min.js` | `public/libs/exe_tooltips/` | Tooltips iDevice | Tooltip rendering library |
| `exe_media/exe_media.js` | `public/libs/exe_media/` | Embedded media iDevice | HTML5 audio/video player helpers |
| `abcjs/abcjs-basic.js` | `public/libs/abcjs/` | ABC music notation iDevice | ABC music notation renderer |


# ===== doc/elpx-format/assets.md =====

# Assets in ELPX Packages

This document covers how project assets (images, audio, video, PDFs, and other binary files) flow through the export/import pipeline: the URL forms an asset reference takes, the export and import transformations that convert between them, and how assets are placed inside the ZIP archive and on the server filesystem.

> **See also**: [ELPX Format hub](../elpx-format.md) | [Themes](themes.md) | [Libraries](libraries.md) | [Screenshot](screenshot.md)

---

## 1. Asset URL lifecycle — three forms

An asset reference passes through three distinct URL forms depending on where it appears.

### 1.1 Yjs internal form — `asset://<uuid>`

While a project is open in the editor, every asset reference in iDevice content is stored in the Yjs Y.Doc as an `asset://` URL:

```
asset://3f7a1b2c-4d5e-6f78-9a0b-1c2d3e4f5678
asset://3f7a1b2c-4d5e-6f78-9a0b-1c2d3e4f5678.jpg
```

Two sub-formats exist:

- `asset://<36-char-uuid>` — UUID without extension (older format).
- `asset://<36-char-uuid>.<ext>` — UUID with file extension appended (current format).

The UUID identifies an entry in the Yjs `assets` Y.Map, which holds the asset's binary data, MIME type, and original filename.

### 1.2 XML export form — `{{context_path}}/<exportPath>`

When content is serialised to `content.xml` (inside `<htmlView>` and `<jsonProperties>` CDATA blocks), `asset://` references are rewritten to a path-template form that points at the resources directory:

```
{{context_path}}/my-image.jpg                 # asset at content/resources/
{{context_path}}/photos/vacation/sunset.jpg   # asset inside a user-created folder
{{context_path}}/lecture-slides.pdf
```

`{{context_path}}` is a placeholder that is resolved at render time to a relative prefix that — combined with the export path — locates the asset under `content/resources/<exportPath>`. The placeholder absorbs both the page-depth `../` and the `content/resources/` segment, so the XML body itself carries only the export path (filename, optionally prefixed by the asset's `folderPath`).

> **Folders are first-class.** The eXeLearning file-manager UI lets authors organise assets into nested folders. Each asset record stores its `folderPath` (`src/shared/export/interfaces.ts:289`), and `BaseExporter.addAssetsToZipWithResourcePath()` (`BaseExporter.ts:429`) preserves it on every export by writing the file to `content/resources/<folderPath>/<filename>`. The XML reference in turn becomes `{{context_path}}/<folderPath>/<filename>`. Don't assume assets are always at the root of `content/resources/`.

> **Compatibility note**: an older long form, `{{context_path}}/content/resources/<exportPath>`, also works because the export pipeline writes assets to the same location. New exports use the short form; importers accept both. See [§3 Import pipeline](#3-import-pipeline).

### 1.3 Final HTML form — resolved relative path

When individual HTML pages are generated, `{{context_path}}` is replaced with the prefix that, when prepended to the filename, yields a valid relative path back to the asset on disk. For an asset stored at `content/resources/my-image.jpg` inside the ZIP, the substitution gives:

```
# index.html (at ZIP root) — {{context_path}} → content/resources
content/resources/my-image.jpg

# html/page-title.html (one level deep) — {{context_path}} → ../content/resources
../content/resources/my-image.jpg
```

The page renderer (`Html5Exporter.generatePageHtml()`, `Html5Exporter.ts:393`) computes the depth-based prefix and substitutes the placeholder inline.

---

## 2. Export pipeline

### 2.1 `BaseExporter.addFilenamesToAssetUrls()` — `asset://` to `{{context_path}}`

The primary transformation happens in `BaseExporter.addFilenamesToAssetUrls()` (`src/shared/export/exporters/BaseExporter.ts:647`).

This method is called during `preprocessPagesForExport()` on every `component.content` string and every serialised `jsonProperties` object before any HTML rendering occurs. It iterates the Yjs `assets` Y.Map to build a `Map<uuid, exportFilename>` (`buildAssetExportPathMap()`) and then rewrites every `asset://` URL it finds. The output is the placeholder-templated form described above.

The `OdeXmlGenerator.transformAssetUrlsForXml()` function (`OdeXmlGenerator.ts:251`) is intentionally a no-op since v4: by the time the generator runs, every `asset://` reference has already been replaced by the preprocessing step.

### 2.2 ZIP placement — `content/resources/<folderPath>/<filename>`

Assets are written into the ZIP by `BaseExporter.addAssetsToZipWithResourcePath()` (`BaseExporter.ts:429`). Each asset lands under `content/resources/` at the export path computed from its `folderPath` and `filename`. Two layouts are valid:

```
# Asset with no folderPath (root of content/resources/)
content/resources/my-image.jpg
content/resources/lecture-slides.pdf

# Assets inside user-created folders (folderPath preserved verbatim)
content/resources/photos/cover.jpg
content/resources/photos/vacation/sunset.jpg
content/resources/handouts/lesson-1/slides.pdf
```

`folderPath` is preserved by every export. There is **no per-asset UUID subfolder** in the v4 layout — that pattern was a v3-era artefact (one `content/resources/<UUID>/<filename>` directory per asset, named after an ODE identifier `[0-9]{14}[A-Z0-9]{6}`). v3-style packages are normalised by the [`scripts/flatten-elpx.ts`](../../scripts/flatten-elpx.ts) tool, which:

1. Walks every `content/resources/<segment>/...` entry where `<segment>` matches the ODE-ID regex `^[0-9]{14}[A-Z0-9]{6}$`. **User-organised folders never match this pattern and are therefore preserved untouched.**
2. SHA-256-hashes contents, deduplicates byte-identical files, and resolves name collisions with `_2`, `_3` suffixes (suffix is appended to the basename, the directory portion stays in place).
3. Rewrites the references inside `content.xml`, `index.html`, and `html/*.html` to match.

Run `bun run scripts/flatten-elpx.ts <input.elpx>` to flatten in place. The script is a no-op when no UUID-pattern folders are present, so it is safe to run on already-clean v4 packages.

### 2.3 `{{context_path}}` resolution during HTML rendering

For each rendered HTML page, the page renderer computes a base prefix:

| Page | Depth | `{{context_path}}` resolves to |
|------|-------|--------------------------------|
| `index.html` | ZIP root | `content/resources` |
| `html/<slug>.html` | one level deep | `../content/resources` |

The substitution is applied to every occurrence of the placeholder in the page body, including `<img src>`, `<a href>`, `<video src>`, `<source src>`, and similar attributes, and to JSON payloads embedded inside `<script type="application/json">` tags.

---

## 3. Import pipeline

On import, `ElpxImporter` reads all iDevice content from `content.xml` and passes strings through `assetHandler.convertContextPathToAssetRefs()`.

The method is invoked in two places:

1. **HTML content** (`ElpxImporter.ts:738`): after building each iDevice's `htmlView`, any `{{context_path}}/<filename>` (or legacy `{{context_path}}/content/resources/<filename>`) pattern is converted back to `asset://<uuid>`.
2. **JSON properties** (`ElpxImporter.ts:1866`): `convertAssetPathsInObject()` recursively walks the properties object. For strings containing `{{context_path}}`, it calls `convertContextPathToAssetRefs()`; for strings starting with `resources/` (legacy non-templated paths), it calls `findAssetUrlForPath()`.

The asset handler maps filenames back to their UUIDs using `this.assetMap`, which is built by extracting all files from the `content/resources/` directory inside the ZIP and registering them as new assets in the Yjs document.

The resulting Yjs document stores only `asset://` URLs — no ZIP-relative paths leak into the editing state.

---

## 4. ZIP placement summary

```
project.elpx (ZIP)
└── content/
    └── resources/
        ├── photo.jpg                    # asset with no folderPath (lives at root of resources)
        ├── slides.pdf
        ├── audio.mp3
        ├── photos/                      # user-created folder (folderPath="photos")
        │   ├── group-shot.jpg
        │   └── vacation/                # nested user folder (folderPath="photos/vacation")
        │       └── sunset.jpg
        └── handouts/lesson-1/           # any user folder depth is permitted
            └── exercises.pdf
```

What you will **not** see in a v4 archive:

- `content/resources/<14-digit-timestamp><6-char-suffix>/<filename>` — that is the legacy v3 per-asset UUID subfolder, normalised by [`scripts/flatten-elpx.ts`](../../scripts/flatten-elpx.ts) on round-trip.

ZIP entries always use forward slashes (`/`) as path separators, regardless of the host operating system, in compliance with the ZIP specification.

---

## 5. Server-side asset storage

On the server, permanent project assets are stored at:

```
FILES_DIR/assets/<projectUuid>/
```

For example:

```
/mnt/data/assets/3f7a1b2c-4d5e-6f78-9a0b-1c2d3e4f5678/photo.jpg
```

`FILES_DIR` resolves in this priority order (from `AGENTS.md §7.3`):

1. `ELYSIA_FILES_DIR` environment variable (used in tests).
2. `FILES_DIR` from `.env`.
3. `./data/` (development fallback).

The project UUID (not the numeric project ID) is always used for the directory name. All code accessing assets must use `path.join()` to construct paths and must call `isPathSafe()` before any file I/O on user-supplied path components.

---

## 6. Permitted asset types and iDevice constraints

Any binary file type may be attached as a project asset. The exporter places it verbatim under `content/resources/` without type checking.

Individual iDevices impose their own constraints at the UI level:

| iDevice | Typical asset types | Notes |
|---------|--------------------|-------|
| Image | `.jpg`, `.jpeg`, `.png`, `.gif`, `.svg`, `.webp` | Raster preferred for lightbox; SVG supported |
| Image gallery | `.jpg`, `.jpeg`, `.png` | Multiple images per iDevice |
| Image magnifier | `.jpg`, `.jpeg`, `.png` | High-resolution raster recommended |
| Audio / Video | `.mp3`, `.ogg`, `.mp4`, `.webm` | URLs (YouTube/Vimeo/MP4) also accepted; file assets for local media |
| Interactive video | Video URL or `.mp4` | YouTube, Vimeo, and direct MP4 links |
| Download source file | Any binary | Typically the project `.elpx` itself or a ZIP bundle; triggers `elpx-manifest.js` generation |
| PDF viewer | `.pdf` | Embedded via browser native PDF viewer or PDF.js |
| File download | Any binary | Presented as a download link |

---

## 7. Cross-platform path rules

- Always construct filesystem paths with `path.join()`. Never concatenate strings with `\\` or `/`.
- ZIP archive entries use `/` separators unconditionally (ZIP spec requirement).
- Asset filenames in `content/resources/` are derived from the original upload filename. The exporter sanitises filenames to remove characters that are invalid on Windows and macOS.
- Duplicate filenames are resolved either by appending a counter suffix before the extension (during export) or by the [`flatten-elpx.ts`](../../scripts/flatten-elpx.ts) deduplication pass (when normalising legacy packages).


# ===== doc/elpx-format/screenshot.md =====

# Project Screenshot in ELPX Packages

This document specifies `screenshot.png` at the root of an `.elpx` ZIP archive — the project-level thumbnail image. It covers the format requirements, the two generation paths, the round-trip through Yjs metadata, and the distinction from the per-theme `theme/screenshot.png`.

> **See also**: [ELPX Format hub](../elpx-format.md) | [Themes](themes.md) | [Libraries](libraries.md) | [Assets](assets.md)

---

## 1. What it is and why it exists

`screenshot.png` is a PNG image placed at the **root** of the `.elpx` ZIP archive. It provides a visual preview of the project's first page without requiring the archive to be fully opened or imported.

In **v4**, every `.elpx` is expected to ship a `screenshot.png` at the root: either the user-provided thumbnail or one generated automatically (see [§5 Two generation paths](#5-two-generation-paths) and [§5.4 Generated placeholder via `add-screenshot.ts`](#54-generated-placeholder-via-add-screenshotts)). The exporter always writes the file, and tooling such as the project browser, validators, and LMS importers may treat its absence as a packaging issue.

Typical use-cases:

- LMS thumbnail grids (Moodle, WordPress, Omeka-S, Drupal LMS plugins).
- File-manager previews in operating systems or CMS media libraries.
- Repository index pages that show thumbnails of published learning objects.
- The eXeLearning project browser, which shows previews of recent projects.

Any tool that can open a ZIP file can extract just the ~100 KB thumbnail in milliseconds without touching the multi-megabyte HTML, library, and asset content.

---

## 2. File location in the archive

`screenshot.png` is always at the archive root — never inside a subdirectory:

```
project.elpx (ZIP)
├── screenshot.png          ← project thumbnail (this document)
├── content.xml
├── index.html
├── theme/
│   └── screenshot.png      ← THEME preview thumbnail (different file)
└── …
```

Example `unzip -l` excerpt:

```
Archive:  project.elpx
  Length      Date    Time    Name
---------  ---------- -----   ----
   102400  2025-04-01 10:00   screenshot.png
 35487232  2025-04-01 10:00   content.xml
   184320  2025-04-01 10:00   index.html
        …                     …
---------                     -------
```

---

## 3. Format specification

### 3.1 Container format

The file must be a **PNG** image. No other image format is accepted.

### 3.2 PNG magic-byte validation

`ElpxExporter.decodeScreenshotToBuffer()` (`src/shared/export/exporters/ElpxExporter.ts:41`) validates the PNG signature before writing the file into the ZIP:

```typescript
private decodeScreenshotToBuffer(screenshot: string): Uint8Array | null {
    // … base64 decode …
    // Validate PNG signature (first 8 bytes)
    if (
        bytes.length >= 8 &&
        bytes[0] === 0x89 &&   // 0x89
        bytes[1] === 0x50 &&   // 'P'
        bytes[2] === 0x4e &&   // 'N'
        bytes[3] === 0x47 &&   // 'G'
        bytes[4] === 0x0d &&   // CR
        bytes[5] === 0x0a &&   // LF
        bytes[6] === 0x1a &&   // SUB
        bytes[7] === 0x0a      // LF
    ) {
        return bytes;
    }
    console.warn('[ElpxExporter] Screenshot data is not a valid PNG');
    return null;
}
```

The eight bytes `89 50 4E 47 0D 0A 1A 0A` are the standard PNG file signature defined in the PNG specification (ISO/IEC 15948). Any data that does not begin with these bytes is silently rejected — `decodeScreenshotToBuffer` returns `null` and no `screenshot.png` is written to the ZIP.

There is no enforced upper limit on file size beyond what the ZIP library and browser memory allow. Practical guidance: keep screenshots under 500 KB for responsive performance in LMS thumbnail views.

### 3.3 Recommended dimensions

**1280 × 720 pixels** (16:9 aspect ratio). This matches the dimensions cited in the hub doc (`elpx-format.md:54`) and aligns with common LMS thumbnail requirements.

Smaller dimensions are accepted; the exporter does not resize or validate dimensions. Images with non-16:9 ratios will be displayed with letterboxing or cropping depending on the consuming tool.

---

## 4. Input format — base64 data URL

The exporter receives the screenshot as a **`data:image/png;base64,…` data URL** stored in the Yjs `metadata` Y.Map under the key `'screenshot'`.

`decodeScreenshotToBuffer()` strips the data URL prefix before decoding:

```typescript
let base64Data = screenshot;
if (base64Data.startsWith('data:')) {
    const commaIndex = base64Data.indexOf(',');
    if (commaIndex === -1) return null;
    base64Data = base64Data.substring(commaIndex + 1);
}
const binaryString = atob(base64Data);
```

Raw base64 strings (without the `data:` prefix) are also accepted by the same code path.

---

## 5. Two generation paths

### 5.1 Custom screenshot from project metadata (priority 1)

If `meta.screenshot` is set (a `data:image/png;base64,…` string from the Yjs metadata), it is used as the screenshot without modification (`ElpxExporter.ts:368`):

```typescript
if (meta.screenshot) {
    screenshotBuffer = this.decodeScreenshotToBuffer(meta.screenshot);
}
```

This is the path taken when the user has explicitly set a screenshot via the project properties dialog.

### 5.2 Auto-generate from first page HTML (priority 2)

If no custom screenshot is set, the exporter checks for an `options.generateScreenshot` async hook (`ElpxExporter.ts:372`):

```typescript
if (!screenshotBuffer && options?.generateScreenshot) {
    try {
        const firstPageHtml = pageHtmlMap.get('index.html');
        if (firstPageHtml) {
            const dataUrl = await options.generateScreenshot(firstPageHtml);
            if (dataUrl) {
                screenshotBuffer = this.decodeScreenshotToBuffer(dataUrl);
            }
        }
    } catch (error) {
        console.warn('[ElpxExporter] Screenshot auto-generation failed:', error);
    }
}
```

`generateScreenshot(html: string): Promise<string | null>` is an optional async callback provided by the caller (the Electron desktop app or the browser export flow). It receives the fully-rendered HTML of `index.html` and returns a `data:image/png;base64,…` data URL, or `null` on failure.

In the **Electron** desktop build, this hook uses an off-screen renderer to capture the first page at 1280×720 and returns the resulting PNG.

In the **browser** export flow, the hook may use an `<html2canvas>` or similar approach; if no hook is provided, auto-generation is skipped.

### 5.3 Omitted when neither path produces a result

If both `meta.screenshot` is absent and `generateScreenshot` is not provided (or returns `null`), no `screenshot.png` is written to the ZIP (`ElpxExporter.ts:385`):

```typescript
if (screenshotBuffer) {
    this.zip.addFile('screenshot.png', screenshotBuffer);
}
```

The importer tolerates the absence — `screenshot.png` is not strictly required to round-trip a project — but for v4 deliverables you should always patch in a thumbnail before publishing. Use [§5.4](#54-generated-placeholder-via-add-screenshotts) to add one to a legacy package.

### 5.4 Generated placeholder via `add-screenshot.ts`

For round-tripped legacy fixtures and any package that arrives without a screenshot, the repo ships [`scripts/add-screenshot.ts`](../../scripts/add-screenshot.ts). It produces a 1280×720 PNG with the project title (read from `<key>pp_title</key>` in `content.xml`) on a brand-coloured background and inserts it at the ZIP root.

```bash
# Add a screenshot in place
bun run scripts/add-screenshot.ts path/to/project.elpx

# Or write a copy with the screenshot patched in
bun run scripts/add-screenshot.ts in.elpx out.elpx

# Force regeneration even when one already exists
bun run scripts/add-screenshot.ts path/to/project.elpx --force
```

The script uses `@napi-rs/canvas` (already a project dependency) to render the title across up to three lines, with font size scaled to fit. It is the recommended way to bring older `.elpx` files (or files produced by stripped-down exporters) up to the v4 baseline without re-opening them in the editor.

---

## 6. Round-trip via Yjs metadata

### 6.1 Import side — `ElpxImporter.extractScreenshotFromZip()`

On import, `ElpxImporter` checks for `screenshot.png` at the archive root (`ElpxImporter.ts:866`):

```typescript
private extractScreenshotFromZip(zip: Record<string, Uint8Array>): string | undefined {
    if (!zip['screenshot.png']) return undefined;
    try {
        const base64 = this.uint8ArrayToBase64(zip['screenshot.png']);
        return `data:image/png;base64,${base64}`;
    } catch (error) {
        this.logger.warn('[ElpxImporter] Failed to read screenshot.png:', error);
        return undefined;
    }
}
```

The PNG bytes are base64-encoded and wrapped in a `data:image/png;base64,…` data URL. This data URL is stored in `metadataValues.screenshot` and subsequently written to the Yjs `metadata` Y.Map via `setMetadata()` (`ElpxImporter.ts:947`):

```typescript
if (values.screenshot) {
    metadata.set('screenshot', values.screenshot);
}
```

### 6.2 Absent screenshot on import

If `screenshot.png` is not present in the archive, `extractScreenshotFromZip` returns `undefined`. The `setMetadata` call omits the `screenshot` key, so the Yjs `metadata` Y.Map has no `'screenshot'` entry. The UI treats this as "no screenshot set" and displays a placeholder in the project properties dialog.

---

## 7. Distinction from `theme/screenshot.png`

These are two entirely separate files with different purposes:

| Property | `screenshot.png` (archive root) | `theme/screenshot.png` |
|----------|--------------------------------|------------------------|
| What it shows | A preview of the **project content** | A preview of the **theme appearance** |
| Who creates it | The eXeLearning exporter (auto or custom) | The theme author |
| Set by | Project settings / auto-capture hook | Shipped with the theme source files |
| Extracted by | `ElpxImporter.extractScreenshotFromZip()` | Theme picker UI |
| Stored in Yjs | `metadata.screenshot` | Not stored in Yjs; only read for display |
| Present in all exports | Yes for v4 (always emitted by the exporter; legacy packages can be patched with [`scripts/add-screenshot.ts`](../../scripts/add-screenshot.ts)) | Yes, whenever the theme is bundled |

The confusion is easy to make because both files are named `screenshot.png` and both are PNG images. The archive root file is always about the project; the `theme/` file is always about the theme's visual design.


# ===== doc/elpx-format/export-pipeline.md =====

# ELPX Export Pipeline

Reference document for the end-to-end process that turns a Yjs document into a
downloadable `.elpx` file.

Related documents: [import-pipeline.md](./import-pipeline.md) |
[validation.md](./validation.md)

---

## 1. Trigger — Two Entry Points

### 1.1 Browser-first (primary path)

The UI invokes `SharedExporters` client-side. The exporter reads the live Yjs
Y.Doc directly, builds the ZIP entirely in memory with `fflate`/JSZip, and
either triggers a browser download or hands the buffer to Electron for a
save-dialog.

`AGENTS.md §7.9` describes this as the primary path: "UI triggers export →
`SharedExporters` generates ZIP in memory → browser downloads (web) or Electron
saves to disk."

The entry point class is `ElpxExporter`, which extends `Html5Exporter`, which
extends `BaseExporter`
(`src/shared/export/exporters/ElpxExporter.ts`,
`src/shared/export/exporters/Html5Exporter.ts`,
`src/shared/export/exporters/BaseExporter.ts`).

### 1.2 Server-side (fallback / CLI / external API)

The server receives `POST /api/export/:sessionId/:exportType/download`. It reads
the project from the database and the Yjs snapshot, reconstructs the document,
instantiates `ElpxExporter`, runs the same pipeline, writes the ZIP to
`FILES_DIR/dist/...`, and streams it back.

CLI equivalents (`Makefile:359-428`):

```
make export-elpx FORMAT=elpx INPUT=/path/to/file.elpx OUTPUT=/path/to/out.elpx
make export-html5 INPUT=...
make export-scorm12 INPUT=...
```

---

## 2. HTML5 Build — `Html5Exporter.export()`

`Html5Exporter.export()` (`Html5Exporter.ts:68`) executes twelve numbered
phases. `ElpxExporter` reuses all of them (calling the same inherited methods)
and adds two extra phases for ELPX-specific files. The phases below reference
the `ElpxExporter.export()` numbering (`ElpxExporter.ts:98`).

### Phase 0 — Theme prefetch

`prepareThemeData(themeName)` (`Html5Exporter.ts:476`) fetches all files for the
active theme. It extracts the list of root-level `.css`/`.js` filenames into
`themeRootFiles` for use in HTML `<head>` includes. It also detects a
`favicon.ico` or `favicon.png` inside the theme. If the fetch fails, fallback
stubs are used (see `getFallbackThemeCss()` / `getFallbackThemeJs()`).

Theme selection priority: export option → `metadata.theme` → `'base'`
(`ElpxExporter.ts:110`).

### Phase 1 — Page HTML generation (`pageHtmlMap`)

`generatePageHtml()` (`Html5Exporter.ts:381`) is called once per page. Before
rendering, `preprocessPagesForExport()` (`BaseExporter.ts:705`) deep-clones all
pages, calls `addFilenamesToAssetUrls()` to rewrite `asset://uuid` references to
`{{context_path}}/content/resources/<exportPath>`, and calls
`replaceInternalLinks()` to rewrite `exe-node:<pageId>` hrefs to relative HTML
paths.

`buildPageFilenameMap()` (`BaseExporter.ts:758`) assigns collision-safe filenames
to all pages. The first page is always `index.html`; subsequent pages are
`html/<sanitized-title>.html`. Collisions are resolved by incrementing trailing
numbers.

Mermaid diagrams are optionally pre-rendered to static SVG via the
`options.preRenderMermaid` hook (`ElpxExporter.ts:175`). When diagrams are
pre-rendered the Mermaid library is not included in the export (saving ~2.7 MB).

Note: LaTeX pre-rendering is disabled in the ELPX exporter (no
`preRenderLatex` hook call) — MathJax runtime handling is used instead.

Pages are buffered in `pageHtmlMap` (a `Map<string, string>`) and written to the
ZIP only after the ELPX manifest is resolved (phase 1.10 / 1.11), so that
manifest `<script>` tags can be injected into the correct pages.

### Phase 1.2 — Search index

When `meta.addSearchBox` is `true`, `pageRenderer.generateSearchIndexFile()` is
called and written to `search_index.js` (`ElpxExporter.ts:199`).

### Phase 1.3 — Base CSS

`resources.fetchContentCss()` returns `content/css/base.css`. If Mermaid was
pre-rendered, the CSS for static SVG rendering is appended inline
(`ElpxExporter.ts:206-220`). The file is written to `content/css/base.css`.

### Phase 1.4 — eXeLearning logo

`resources.fetchExeLogo()` is fetched and written to
`content/img/exe_powered_logo.png` for the "Made with eXeLearning" footer
(`ElpxExporter.ts:225-233`).

### Phase 1.5 — Theme files

All files from the pre-fetched `themeFilesMap` are written under `theme/`
(`ElpxExporter.ts:235-243`). If prefetch failed, the two fallback stubs are
written as `theme/style.css` and `theme/style.js`.

### Phase 1.6 — Base libraries

`resources.fetchBaseLibraries()` returns jQuery, Bootstrap, `common.js`,
`exe_export.js`, and related files. These are always included
(`ElpxExporter.ts:247-259`). See `constants.ts:325-337` for the full list.

A localised `libs/common_i18n.js` is generated from the project's content
language via `generateI18nContent()` (`ElpxExporter.ts:261-262`).

### Phase 1.7 — Content-driven libraries

`getRequiredLibraryFilesForPages()` (`BaseExporter.ts:943`) iterates all
component HTML fragments to detect which optional libraries are needed (effects,
games, media player, tooltips, MathJax, ELPX download support, etc.). The full
pattern list is in `constants.ts:107-315`.

Detected files are fetched and added under `libs/`. Files already present from
phase 1.6 are skipped (`ElpxExporter.ts:278`).

### Phase 1.8 — Per-iDevice assets

`getUsedIdevices()` collects all distinct iDevice type names. For each type,
`resources.fetchIdeviceResources()` is called and files are written under
`idevices/<normalizedType>/` (`ElpxExporter.ts:289-309`). Missing iDevice
resource directories are silently skipped (normal for most iDevice types).

### Phase 1.9 — Project assets

`addAssetsToZipWithResourcePath()` (`BaseExporter.ts:429`) iterates every asset
in the project, resolves its export path from `buildAssetExportPathMap()`, and
writes it to `content/resources/<exportPath>`. The export path map uses the
asset's `folderPath` metadata to recreate the original folder structure, with
collision detection (`BaseExporter.ts:560-623`).

### Phase 1.10 / 1.11 — ELPX download manifest and HTML pages

If any page contains a `download-source-file` iDevice or an `exe-package:elp`
link (`needsElpxDownloadSupport()`, `BaseExporter.ts:961`), a manifest file is
generated:

1. `generateElpxManifestFile(fileList)` (`BaseExporter.ts:1060`) produces
   `libs/elpx-manifest.js` containing `window.__ELPX_MANIFEST__` with the
   complete file list and project title.
2. Pages that contain the iDevice get a `<script src="libs/elpx-manifest.js">`
   tag injected before `</body>` (`ElpxExporter.ts:334-338`).

HTML pages are then written to the ZIP: first page as `index.html`, remaining
pages as `html/<uniqueFilename>` (`ElpxExporter.ts:327-339`).

---

## 3. ELPX-specific Add-ons — Section 2 of `ElpxExporter.export()`

These three steps are unique to ELPX and do not appear in the base HTML5 export.

### Phase 2.1 — `content.xml`

`generateOdeXml(meta, pages)` (`OdeXmlGenerator.ts:43`) is called with the
preprocessed pages. The generated XML is immediately validated:

```
validateXml(contentXml)  // src/services/xml/xml-parser.ts:134
formatValidationErrors(validation)
```

If validation fails, the export is aborted with an error
(`ElpxExporter.ts:350-355`). The validated XML is written to `content.xml`
(`ElpxExporter.ts:360`).

`generateOdeXml` emits the following XML skeleton
(`OdeXmlGenerator.ts:43-72`):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ode SYSTEM "content.dtd">
<ode xmlns="http://www.intef.es/xsd/ode" version="2.0">
  <userPreferences>  <!-- theme key -->
  <odeResources>     <!-- odeId, odeVersionId, exe_version -->
  <odeProperties>    <!-- all ExportMetadata fields -->
  <odeNavStructures> <!-- one <odeNavStructure> per page -->
```

Each page node (`generateOdeNavStructureXml`, `OdeXmlGenerator.ts:154`) contains
`<odePageId>`, `<odeParentPageId>`, `<pageName>`, `<odeNavStructureOrder>`,
`<odeNavStructureProperties>`, and `<odePagStructures>`.

Each block (`generateOdePagStructureXml`, `OdeXmlGenerator.ts:200`) contains
`<odeBlockId>`, `<blockName>`, `<iconName>`, `<odePagStructureOrder>`, and
`<odeComponents>`.

Each component (`generateOdeComponentXml`, `OdeXmlGenerator.ts:258`) contains:
- `<odeIdeviceTypeName>` — the iDevice type string
- `<htmlView>` — pre-rendered HTML wrapped in CDATA
- `<jsonProperties>` — serialised JSON wrapped in CDATA
- `<odeComponentsOrder>`

CDATA content that contains the sequence `]]>` is split using the escape
`]]]]><![CDATA[>` (`OdeXmlGenerator.ts:352`).

The ODE identifier format is `YYYYMMDDHHmmss` + 6 uppercase alphanumeric chars
(`generateOdeId()`, `OdeXmlGenerator.ts:315`).

### Phase 2.2 — `content.dtd`

The constant `ODE_DTD_CONTENT` (`constants.ts:1006`) is written verbatim as
`content.dtd` (`ElpxExporter.ts:363`). The DTD filename is `ODE_DTD_FILENAME =
'content.dtd'` (`constants.ts:995`).

### Phase 2.3 — `screenshot.png`

Screenshot selection follows a priority chain (`ElpxExporter.ts:365-387`):

1. `meta.screenshot` — base64 data URL stored in project metadata (custom
   screenshot set by the user).
2. `options.generateScreenshot(firstPageHtml)` — browser hook that renders the
   `index.html` page to a PNG data URL.
3. If neither produces a valid PNG, no screenshot is included.

`decodeScreenshotToBuffer()` (`ElpxExporter.ts:41`) decodes the base64 payload
and validates the PNG magic bytes `89 50 4E 47 0D 0A 1A 0A`. Invalid data is
silently discarded.

---

## 4. ZIP Packaging — Section 3 of `ElpxExporter.export()`

`this.zip.generateAsync()` (`ElpxExporter.ts:395`) compresses all accumulated
files with deflate and returns a `Buffer`. The returned `ExportResult` contains
the buffer and the export filename built by `buildFilename()`
(`BaseExporter.ts:392`):

```
<sanitized-title><suffix><extension>
// Example: my-project.elpx  (suffix = '', extension = '.elpx')
```

Debug timing information is optionally logged to
`window.__currentElpxExportTrace` when
`window.eXeLearning.config.debugElpxExport = true`
(`BaseExporter.ts:64-115`).

---

## 5. Distribution

| Path | Description |
|------|-------------|
| Browser download | `ExportResult.data` buffer is converted to a blob URL |
| Electron save | Main process writes the buffer to the user-chosen path |
| Server response | Buffer streamed back as `Content-Type: application/zip` |
| CLI | `make export-elpx` / `make export-html5` write to `OUTPUT` path |

---

## End-to-End Flow Diagram

```
UI click / CLI call
        |
        v
  ElpxExporter.export()
        |
        +--[Phase 0]----> prepareThemeData()
        |                  themeFilesMap, themeRootFiles, faviconInfo
        |
        +--[Phase 1]----> preprocessPagesForExport()
        |                  addFilenamesToAssetUrls()
        |                  replaceInternalLinks()
        |                  buildPageFilenameMap()
        |                  generatePageHtml() x N  --> pageHtmlMap
        |                  optional Mermaid pre-render
        |
        +--[1.2]---------> search_index.js (optional)
        +--[1.3]---------> content/css/base.css
        +--[1.4]---------> content/img/exe_powered_logo.png
        +--[1.5]---------> theme/* (all theme files)
        +--[1.6]---------> libs/jquery, bootstrap, common.js ...
        |                  libs/common_i18n.js
        +--[1.7]---------> libs/<detected optional libs>
        +--[1.8]---------> idevices/<type>/*
        +--[1.9]---------> content/resources/<assetPath>
        +--[1.10]--------> libs/elpx-manifest.js (if download-source-file)
        +--[1.11]--------> index.html, html/*.html
        |
        +--[2.1]---------> generateOdeXml() --> validateXml() --> content.xml
        +--[2.2]---------> content.dtd
        +--[2.3]---------> screenshot.png (if available)
        |
        +--[3]-----------> zip.generateAsync()
                            |
                            v
                      Buffer + filename
                            |
               +------------+------------+
               |            |            |
          Browser        Electron      Server
          download     save dialog    stream/dist
```


# ===== doc/elpx-format/import-pipeline.md =====

# ELPX Import Pipeline

Reference document for the end-to-end process that reads an `.elpx` (or legacy
`.elp`) file and populates a Yjs document with the project structure.

Related documents: [export-pipeline.md](./export-pipeline.md) |
[validation.md](./validation.md)

---

## Architecture Summary

The import path is **entirely browser-side** in the normal workarea flow. The
server never parses ELP/ELPX files during a regular import (`AGENTS.md §7.8`).

Two paths exist:

1. **Direct import (primary):** user selects `.elp`/`.elpx` → browser imports
   in memory via `ElpxImporter` → UI refreshes from Y.Doc → saved to server on
   explicit save/autosave.
2. **Chunked upload (fallback):** browser uploads in 15 MB chunks to
   `POST /api/project/upload-chunk` → server concatenates into a temp file (no
   parsing) → browser reloads workarea with `?import=…` → browser calls
   `DELETE /api/project/cleanup-import` to remove the temp file.

The server-side `ElpxImporter` (`src/shared/import/ElpxImporter.ts`) is also
used by CLI export commands and the external API when they need to build a Y.Doc
from a file on disk.

---

## Phase 1 — Decompression

**Responsibility:** `ElpxImporter.importFromBuffer()` (`ElpxImporter.ts:160`)

```typescript
const zip = fflate.unzipSync(buffer);  // ElpxImporter.ts:173
```

`fflate.unzipSync` decompresses the entire ZIP into a
`Record<string, Uint8Array>` keyed by file path.

After decompression, `unwrapSingleTopLevelDirectory()` (`ElpxImporter.ts:112`)
strips a single top-level folder prefix if every entry shares the same prefix.
This handles archives exported from GitHub (e.g. `repo-main/content.xml`
becomes `content.xml`).

**Nested ELP detection:** if neither `content.xml` nor `contentv3.xml` exists at
root, the importer searches for a single `.elp`/`.elpx` file at root level
(`ElpxImporter.ts:183-195`). If exactly one is found it is recursively
decompressed. If more than one is found an error is thrown.

---

## Phase 2 — Format Detection

**Responsibility:** `ElpxImporter.importFromBuffer()` (`ElpxImporter.ts:196-266`)

The detection logic checks file presence in the following order:

```
content.xml present?      --> modern ODE format
contentv3.xml present?    --> legacy Python pickle format
EPUB/content.xml present? --> EPUB3 package (paths stripped of EPUB/ prefix,
                              then re-evaluated as modern ODE format)
none found?               --> Error: "content.xml is missing"
```

Once the content file is found and decoded, it is parsed with
`@xmldom/xmldom`'s `DOMParser` (`ElpxImporter.ts:241`). Parsing errors raise
immediately.

**Root element inspection** determines the format branch
(`ElpxImporter.ts:250-266`):

| Root element | Format | Handler |
|---|---|---|
| `<ode>` | Modern ODE XML | `importStructure()` |
| `<instance class="exe.engine.package.Package">` or `<dictionary>` | Legacy Python pickle | `LegacyXmlParser` + `importLegacyStructure()` |

---

## Phase 3 — Asset Extraction

**Responsibility:** `importAssets()` called at the start of both
`importStructure()` and `importLegacyStructure()` (`ElpxImporter.ts:376`,
`ElpxImporter.ts:547`)

Assets live inside the ZIP under `content/resources/`. The `AssetHandler`
implementation (`assetHandler`) determines where they end up:

- **Browser:** the `BrowserAssetHandler` stores blobs in the Cache API under
  `exe-assets-{uuid}`.
- **Server / CLI:** the `FileSystemAssetHandler` writes files to
  `FILES_DIR/assets/{projectUuid}/`.

After extraction, `assetMap` is populated (`Map<string, string>`) mapping
original file paths to their new asset UUIDs or internal references. This map
is used later to convert `{{context_path}}/content/resources/<file>` paths back
to `asset://<uuid>` internal references inside `htmlView` and `jsonProperties`.

Progress: `reportProgress('assets', 10 → 50, ...)` (`ElpxImporter.ts:373`, 379`).

---

## Phase 4 — XML Parsing and Page/Block/Component Reconstruction

### 4a — Modern ODE Format: `importStructure()`

**Responsibility:** `ElpxImporter.ts:364`

1. `findNavStructures(xmlDoc)` — collects all `<odeNavStructure>` elements.
2. A `pageMap` is built keying each element by its `<odePageId>` text content.
3. Root-level pages are identified by empty or missing `<odeParentPageId>`, then
   sorted by `<odeNavStructureOrder>`.
4. `buildFlatPageList()` (`ElpxImporter.ts:952`) performs a depth-first
   traversal. For each page:
   - A fresh `newPageId` is generated (`generateId('page')`).
   - `idRemap` records `originalId → newPageId` for later link rewriting.
   - `buildPageData()` (`ElpxImporter.ts:1012`) extracts page name, order,
     properties, and then iterates `<odePagStructure>` elements to build
     `BlockData` objects via `buildBlockData()` (`ElpxImporter.ts:1055`).
   - Within each block, `buildComponentData()` (`ElpxImporter.ts:1095`)
     extracts the iDevice type, `htmlView` CDATA content, `jsonProperties`
     CDATA content (parsed as JSON), and structure properties.

**ID remap for collisions:** because the same ELPX file might be imported
multiple times into the same Y.Doc (incremental import), all page IDs are
regenerated on every import. If `clearExisting = false` (incremental import),
`getNextAvailableOrder()` is called to compute an order offset so new root pages
are appended after existing ones.

**Type normalisation in `buildComponentData()`** (`ElpxImporter.ts:1101-1109`):
the iDevice type is read first from `odeIdeviceTypeDirName` attribute, then
`odeIdeviceTypeName` element text. The `LEGACY_TYPE_ALIASES` map
(`interfaces.ts:193`) is applied:

| Old type name | Mapped to |
|---|---|
| `download-package` | `download-source-file` |

### 4b — Legacy Python Pickle Format: `LegacyXmlParser`

**Responsibility:** `src/shared/import/LegacyXmlParser.ts`

`LegacyXmlParser.parse()` (`LegacyXmlParser.ts:379`) preprocesses the XML
(whitespace normalisation, hex escape decoding), then parses with
`@xmldom/xmldom`.

It finds all `<instance class="exe.engine.node.Node">` elements
(`findAllNodes()`), builds a parent reference map, and reconstructs the page
hierarchy with `buildPageHierarchy()`.

iDevice instances are read from `<instance class="...Idevice">` elements inside
each node's `idevices` list. Type determination follows a three-way branch
(`LegacyXmlParser.ts:1235-1313`):

**Branch 1 — JsIdevice** (`exe.engine.jsidevice.JsIdevice`): the `_iDeviceDir`
dict entry path suffix maps to a modern type via `jsIdeviceTypeMap`
(`LegacyXmlParser.ts:1242`):

| Legacy `_iDeviceDir` suffix | Modern type |
|---|---|
| `adivina-activity` | `guess` |
| `candado-activity` | `padlock` |
| `clasifica-activity` | `classify` |
| `completa-activity` | `complete` |
| `desafio-activity` | `challenge` |
| `descubre-activity` | `discover` |
| `flipcards-activity` | `flipcards` |
| `identifica-activity` | `identify` |
| `listacotejo-activity` | `checklist` |
| `mapa-activity` | `map` |
| `mathematicaloperations-activity` | `mathematicaloperations` |
| `mathproblems-activity` | `mathproblems` |
| `ordena-activity` | `sort` |
| `quext-activity` | `quick-questions` |
| `relaciona-activity` | `relate` |
| `rosco-activity` | `az-quiz-game` |
| `selecciona-activity` | `quick-questions-multiple-choice` |
| `seleccionamedias-activity` | `select-media-files` |
| `sopa-activity` | `word-search` |
| `trivial-activity` | `trivial` |
| `videoquext-activity` | `quick-questions-video` |
| `download-package` | `download-source-file` |
| `form-activity` | `form` |
| `rubrics` | `rubric` |
| `pbl-tools` | `text` |
| (unknown) | `text` |

**Branch 2 — GenericIdevice:** the `__name__` dict entry is read and passed to
`mapGenericIdeviceType()`.

**Branch 3 — all other class names:** `mapIdeviceType(className)`
(`LegacyXmlParser.ts:1110`) is called, which applies two lookup tables:

Text-based legacy types (all map to `text`):

`FreeTextIdevice`, `FreeTextfpdIdevice`, `GenericIdevice`, `TextIdevice`,
`ActivityIdevice`, `TaskIdevice`, `ObjectivesIdevice`, `PreknowledgeIdevice`,
`ReadingActivityIdevice`, `ReflectionIdevice`, `ReflectionfpdIdevice`,
`ReflectionfpdmodifIdevice`, `TareasIdevice`, `ListaApartadosIdevice`,
`ComillasIdevice`, `NotaInformacionIdevice`, `NotaIdevice`,
`CasopracticofpdIdevice`, `CitasparapensarfpdIdevice`, `DebesconocerfpdIdevice`,
`DestacadofpdIdevice`, `OrientacionestutoriafpdIdevice`,
`OrientacionesalumnadofpdIdevice`, `ParasabermasfpdIdevice`,
`RecomendacionfpdIdevice`, `WikipediaIdevice`, `RssIdevice`, `AppletIdevice`,
`FileAttachIdevice`, `AttachmentIdevice`

Interactive legacy types (`interactiveTypeMap`, `LegacyXmlParser.ts:1151`):

| Legacy class name | Modern type |
|---|---|
| `TrueFalseIdevice` | `trueorfalse` |
| `VerdaderofalsofpdIdevice` | `trueorfalse` |
| `MultichoiceIdevice` | `form` |
| `EleccionmultiplefpdIdevice` | `form` |
| `MultiSelectIdevice` | `form` |
| `SeleccionmultiplefpdIdevice` | `form` |
| `ClozeIdevice` | `complete` |
| `ClozefpdIdevice` | `complete` |
| `ClozelangfpdIdevice` | `complete` |
| `ImageMagnifierIdevice` | `magnifier` |
| `GalleryIdevice` | `image-gallery` |
| `CasestudyIdevice` | `casestudy` |
| `EjercicioresueltofpdIdevice` | `casestudy` |
| `ExternalUrlIdevice` | `external-website` |
| `QuizTestIdevice` | `quick-questions` |
| (anything else matching `\w+Idevice`) | `text` |

---

## Phase 5 — Metadata Extraction and Screenshot

**Responsibility:** `extractMetadata()` (`ElpxImporter.ts:881`) and
`extractScreenshotFromZip()` (`ElpxImporter.ts:866`)

For modern ODE format, metadata is read from the `<odeProperties>` element via
`getMetadataProperty()` / `getBooleanMetadataProperty()`. Properties use the
`pp_` prefix convention (`pp_title`, `pp_author`, `pp_lang`, `pp_license`, etc.)
(`ElpxImporter.ts:901-921`).

Theme is extracted from `<userPreferences>` first (key `theme`), falling back to
`odeProperties` key `pp_style` (`ElpxImporter.ts:884-896`).

`setMetadata()` (`ElpxImporter.ts:927`) writes all extracted values into the
Yjs `metadata` Y.Map.

**Screenshot:** `extractScreenshotFromZip()` looks for `screenshot.png` at the
archive root, base64-encodes it, and stores it as a `data:image/png;base64,...`
data URL in `metadata.screenshot` (`ElpxImporter.ts:866-876`, `423-426`).

For legacy format, `setLegacyMetadata()` (`ElpxImporter.ts:793`) sets the same
keys. Legacy files always get `theme = 'base'` and `addMathJax = false`
(`ElpxImporter.ts:800-811`).

---

## Phase 6 — Internal Link Remap

**Responsibility:** `remapInternalPageLinks()` (`ElpxImporter.ts:1453`)

Because all page IDs are regenerated during import, any `href="exe-node:<oldId>"`
links inside `htmlView` content and `jsonProperties` string values must be
updated to point to the new IDs.

A single regex is built from the union of all old IDs
(`ElpxImporter.ts:1457-1458`), then applied to both `comp.htmlView` and all
string values inside `comp.properties` recursively via `remapLinksInObject()`
(`ElpxImporter.ts:1486`). Anchor fragments (`#section`) are preserved.

The same remapping is applied in the legacy path via
`convertLegacyPagesToPageData()` (`ElpxImporter.ts:686`).

---

## Phase 7 — Yjs Transaction

**Responsibility:** `ElpxImporter.ts:466` (modern) / `ElpxImporter.ts:573`
(legacy)

All Y.Doc mutations are wrapped in a single `ydoc.transact()` call to produce
one combined undo step and avoid incremental observer firing.

Inside the transaction:
1. If `clearExisting = true`, the `navigation` Y.Array is cleared
   (`while (navigation.length > 0) navigation.delete(0)`).
2. Metadata is written to the `metadata` Y.Map (only when clearing).
3. Each `PageData` in the flat list is converted to a Y.Map via
   `createPageYMap()` (`ElpxImporter.ts:1279`) and pushed to `navigation`.

Progress advances from 50% to 80% over this phase.

After the transaction, `assetHandler.preloadAllAssets()` is called if available
(phase 4 / 80–100%).

---

## Progress Phases Summary

| Phase constant | Percent range | Description |
|---|---|---|
| `decompress` | 0 → 10 | ZIP decompression |
| `assets` | 10 → 50 | Asset extraction |
| `structure` | 50 → 80 | Page/block/component reconstruction |
| `precache` | 80 → 100 | Asset preloading |

---

## End-to-End Flow Diagram

```
Buffer (.elpx / .elp)
        |
        v
  fflate.unzipSync()  [ElpxImporter.ts:173]
        |
        v
  unwrapSingleTopLevelDirectory()
        |
        +-- nested ELP? --> unzipSync again
        |
        v
  content.xml?  contentv3.xml?  EPUB/content.xml?
        |               |               |
        v               v               v
   DOMParser      LegacyXmlParser   strip EPUB/
        |               |           prefix, retry
        |               |
        |    +----------+
        |    |
        v    v
  importStructure()   importLegacyStructure()
        |                     |
        +----------+----------+
                   |
                   v
          importAssets()  [content/resources/ --> AssetHandler]
                   |
                   v
  extractMetadata() + extractScreenshotFromZip()
                   |
                   v
  buildFlatPageList() / convertLegacyPagesToPageData()
    -- generateId() for all page/block/component IDs
    -- buildComponentData(): read htmlView, jsonProperties
    -- convertContextPathToAssetRefs(): {{context_path}} --> asset://
                   |
                   v
  remapInternalPageLinks()  [exe-node:<old> --> exe-node:<new>]
                   |
                   v
  ydoc.transact()
    -- navigation.delete(0) x N  (if clearExisting)
    -- metadata.set(...)
    -- navigation.push([createPageYMap(pageData)])
                   |
                   v
  assetHandler.preloadAllAssets()
                   |
                   v
  ElpxImportResult { pages, blocks, components, assets, theme, zipContents }
```


# ===== doc/elpx-format/validation.md =====

# ELPX Validation

A practical guide to validating `.elpx` packages, their `content.xml`, and the
HTML output they carry.

Related documents: [export-pipeline.md](./export-pipeline.md) |
[import-pipeline.md](./import-pipeline.md)

---

## 1. DTD vs XSD — When Each Is Used

Two schema artefacts ship with the project.

### DTD — `content.dtd`

- **Location in a package:** bundled at the ZIP root alongside `content.xml`.
- **Location in the source tree:** `public/app/schemas/ode/content.dtd` (also
  embedded verbatim as the `ODE_DTD_CONTENT` constant in
  `src/shared/export/constants.ts:1006`).
- **Written into every ELPX** during export phase 2.2
  (`ElpxExporter.ts:363`).
- **Purpose:** offline structural validation. Any XML tool can validate
  `content.xml` without network access by resolving the `SYSTEM "content.dtd"`
  declaration against the bundled file.
- **Limitations:** DTD cannot enforce data types, regex patterns, or enumerated
  values — only element presence and nesting.

### XSD — `ode-content.xsd`

- **Location in source:** `public/app/schemas/ode/ode-content.xsd`.
- **Not bundled** in exported `.elpx` packages.
- **Purpose:** stricter offline or CI validation. Adds:
  - `odeIdentifierType` — pattern `[0-9]{14}[A-Z0-9]{6}|page-[a-z0-9-]+|[a-zA-Z0-9_-]+`
    (`ode-content.xsd:148-152`).
  - `ideviceTypeType` — enumeration of all known iDevice type names
    (`ode-content.xsd:158-235`).
  - `booleanStringType` — restricts property values to `true`/`false`/`True`/`False`
    (`ode-content.xsd:242-249`).
  - `propertyKeyType` — enumeration of known `<key>` values in `odeProperties`
    (`ode-content.xsd:255-291`).
  - Integer types on order fields (`odeNavStructureOrder`, `odePagStructureOrder`,
    `odeComponentsOrder`).

### Coverage Matrix

| Check | DTD | XSD |
|---|---|---|
| Root element `<ode>` present | yes | yes |
| `<odeNavStructures>` required | yes | yes |
| `<odePageId>` required in each page | yes | yes |
| `<odeBlockId>` required in each block | yes | yes |
| `<odeIdeviceId>` required in each component | yes | yes |
| `<odeIdeviceTypeName>` required | yes | yes |
| Order fields are integers | no | yes |
| Identifier format (timestamp + random) | no | yes |
| iDevice type must be a known value | no | yes |
| Property keys enumerated | no | yes |
| Boolean string values restricted | no | yes |

---

## 2. Programmatic Validation — `OdeXmlValidator`

`src/services/xml/ode-xml-validator.ts` implements structural validation that
runs at export time and can be called by integrators.

### API

```typescript
import { validateOdeXml, formatValidationErrors } from './ode-xml-validator';
import type { ValidationResult } from './ode-xml-validator';

const result: ValidationResult = validateOdeXml(parsedObject);
// parsedObject is the output of fast-xml-parser or equivalent

if (!result.valid) {
    console.error(formatValidationErrors(result));
}
```

`validateXml(xmlString)` in `src/services/xml/xml-parser.ts:134` wraps
`validateOdeXml` to accept a raw XML string directly:

```typescript
import { validateXml, formatValidationErrors } from '../services/xml/xml-parser';

const result = validateXml(contentXmlString);
if (!result.valid) throw new Error(formatValidationErrors(result));
```

This is the exact call made inside `ElpxExporter.export()` before writing
`content.xml` (`ElpxExporter.ts:350-355`). An invalid XML causes the export to
abort.

### `ValidationResult` shape

```typescript
interface ValidationResult {
    valid: boolean;
    errors: ValidationError[];    // severity: 'error' — block export
    warnings: ValidationError[];  // severity: 'warning' — logged, not blocking
}

interface ValidationError {
    code: string;   // e.g. 'MISSING_PAGE_ID'
    message: string;
    path: string;   // XPath-like, e.g. '/ode/odeNavStructures/odeNavStructure[0]'
    severity: 'error' | 'warning';
}
```

### What the validator checks

- `MISSING_ROOT` — no `<ode>` element (legacy formats are accepted as-is).
- `INVALID_NAMESPACE` — `xmlns` present but not `http://www.intef.es/xsd/ode`
  (warning only).
- `MISSING_NAV_STRUCTURES` — `<odeNavStructures>` absent.
- Per `<odeNavStructure>`: `MISSING_PAGE_ID`, `MISSING_PAGE_NAME`,
  `MISSING_NAV_ORDER`.
- Per `<odePagStructure>`: `MISSING_BLOCK_PAGE_ID`, `MISSING_BLOCK_ID`,
  `MISSING_PAG_ORDER`.
- Per `<odeComponent>`: `MISSING_COMP_PAGE_ID`, `MISSING_COMP_BLOCK_ID`,
  `MISSING_IDEVICE_ID`, `MISSING_IDEVICE_TYPE`, `MISSING_COMP_ORDER`.
- `NO_CONTENT` — component has neither `<htmlView>` nor `<jsonProperties>`
  (warning only, `ode-xml-validator.ts:506-513`).

The validator does **not** check file references inside `htmlView`, asset
presence in `content/resources/`, or HTML well-formedness.

---

## 3. Mandatory Presence Checklist

Use this checklist to verify a third-party `.elpx` package before importing it.

### 3.1 Archive structure

- [ ] ZIP is valid and decompressible by `fflate.unzipSync()`.
- [ ] `content.xml` present at the archive root (or inside `EPUB/` for EPUB3
      packages, or as a single nested `.elp`/`.elpx` at root).
- [ ] `content.dtd` present at the archive root — **required for v4
      packages**. Bundled by `ElpxExporter` from `ODE_DTD_CONTENT`
      (`constants.ts:1006`). Validators (and humans running `xmllint`) need
      it.
- [ ] `index.html` present at the archive root — absence makes the package
      non-viewable offline. The importer tolerates its absence but the package
      is then not self-contained.
- [ ] `screenshot.png` present at the archive root — **required for v4
      packages**. PNG magic bytes `89 50 4E 47 0D 0A 1A 0A` validated. If
      missing on a legacy file, patch with [`scripts/add-screenshot.ts`](../../scripts/add-screenshot.ts).
- [ ] `theme/` directory present with at least `config.xml`, `style.css`,
      `style.js`, and (per v4) `theme/screenshot.png`.
- [ ] `libs/` contains the base libraries from `BASE_LIBRARIES`
      (`constants.ts:325`): `jquery/jquery.min.js`, `common.js`,
      `common_i18n.js`, `exe_export.js`, `bootstrap/bootstrap.bundle.min.js`,
      `bootstrap/bootstrap.min.css`.
- [ ] `idevices/<type>/` directory present for every `<odeIdeviceTypeName>`
      referenced in `content.xml`, with the type's `<type>.js`, `<type>.css`,
      and `<type>.html` files.
- [ ] `content/resources/` mirrors the project's asset tree: assets without
      a `folderPath` live at the root, and user-created folders appear as
      real subdirectories. **Reject** any path matching the legacy v3
      pattern `content/resources/[0-9]{14}[A-Z0-9]{6}/...` — that is a
      per-asset UUID subfolder from a v3 export and should be normalised
      with [`scripts/flatten-elpx.ts`](../../scripts/flatten-elpx.ts) (the
      script preserves user folders, since they never match the ODE-ID
      regex).

### 3.2 `content.xml` structure

- [ ] XML is well-formed (parses without `<parsererror>`).
- [ ] Passes `validateXml()` with zero errors (`valid: true`).
- [ ] Root element is `<ode xmlns="http://www.intef.es/xsd/ode" version="2.0">`.
- [ ] At least one `<odeNavStructure>` child of `<odeNavStructures>`.
- [ ] Every `<odeComponent>` has an `<odePageId>` and `<odeBlockId>` matching
      the `<odePageId>` and `<odeBlockId>` of its enclosing
      `<odeNavStructure>` / `<odePagStructure>`.

### 3.3 Content integrity

- [ ] No unresolved template placeholders remain in any `htmlView` or HTML
      file: `__PLACEHOLDER__`, literal `{{context_path}}` (outside of resolved
      HTML files), `UUID-PAGINA`, `UUID-BLOQUE`.
- [ ] All `src=` / `href=` references in `htmlView` CDATA and in `html/*.html`
      that are relative paths resolve to a file inside the ZIP, or are absolute
      external URLs beginning with `http://` or `https://`.
- [ ] For text-like iDevices: `htmlView` and `jsonProperties.textTextarea` are
      semantically aligned (both represent the same content; `htmlView` is the
      rendered form, `jsonProperties.textTextarea` is the editable source used
      by the workarea).
- [ ] All asset paths under `content/resources/` referenced in `htmlView`
      follow the form `{{context_path}}/<filename>` (v4 flat form) or the
      legacy `{{context_path}}/content/resources/<filename>` form, and the
      corresponding file exists in the ZIP at `content/resources/<filename>`
      (no UUID subfolder).

### 3.4 Optional assets

- [ ] `screenshot.png` (validated as required in §3.1) starts with the PNG
      magic bytes `89 50 4E 47 0D 0A 1A 0A` (8 bytes). The importer validates
      this via `decodeScreenshotToBuffer()` (`ElpxExporter.ts:41-74`) and
      silently discards an invalid screenshot.
- [ ] If `libs/elpx-manifest.js` is present it contains a valid
      `window.__ELPX_MANIFEST__` assignment with a `files` array and
      `projectTitle` string.

---

## 4. Common Rejection Causes

| Cause | Where detected | Notes |
|---|---|---|
| Missing `<odeNavStructures>` element | `validateOdeXml()` / `ode-xml-validator.ts:85` | Export aborts; import produces empty document |
| XML not well-formed (unclosed tag, bad entity) | `DOMParser` in `ElpxImporter.ts:241` | Throws "XML parsing error: …" |
| `content.xml` absent | `ElpxImporter.ts:232` | Error: "content.xml is missing" |
| Multiple nested `.elp`/`.elpx` files at root | `ElpxImporter.ts:193` | Error: "ZIP contains multiple ELP files" |
| `screenshot.png` not valid PNG | `decodeScreenshotToBuffer()` `ElpxExporter.ts:57-70` | Screenshot silently dropped at export time |
| `]]>` inside CDATA not escaped | `escapeCdata()` `OdeXmlGenerator.ts:352` | CDATA closed prematurely; XML becomes malformed |
| `asset://` URLs not resolved in `htmlView` | `addFilenamesToAssetUrls()` `BaseExporter.ts:647` | Broken image/media in exported HTML |
| Duplicate `<odePageId>` values | Not validated by current code | Importer creates two pages with the same Yjs entry; behaviour undefined |
| JSON in `<jsonProperties>` not parseable | `buildComponentData()` `ElpxImporter.ts:1165` | Logs warning, uses empty `{}` — component loses its interactive state |

---

## 5. How to Validate

### 5.1 With `xmllint` (DTD)

Unzip the `.elpx` first, then run from the unzipped directory:

```bash
cd /tmp/my-project-unpacked
xmllint --noout --dtdvalid content.dtd content.xml
```

A clean exit (no output, status 0) means DTD validation passed.

### 5.2 With `xmllint` (XSD)

```bash
xmllint --noout --schema /path/to/ode-content.xsd content.xml
```

The XSD is not bundled inside the ELPX; use the copy from the source tree at
`public/app/schemas/ode/ode-content.xsd`.

Note: `xmllint` validates against the target namespace
`http://www.intef.es/xsd/ode`. The `<ode>` root element must carry
`xmlns="http://www.intef.es/xsd/ode"` for the XSD to match.

### 5.3 Programmatically (`OdeXmlValidator` + `xml-parser`)

```typescript
import { validateXml, formatValidationErrors } from 'src/services/xml/xml-parser';
import * as fs from 'fs';

const xml = fs.readFileSync('content.xml', 'utf-8');
const result = validateXml(xml);

if (!result.valid) {
    console.error('INVALID:\n' + formatValidationErrors(result));
    process.exit(1);
}
if (result.warnings.length > 0) {
    console.warn('WARNINGS:\n' + formatValidationErrors(result));
}
console.log('OK');
```

Pass `{ skipValidation: true }` to `parseFromString()` if you need to parse
without validation (e.g. importing deliberately non-standard files).

Pass `{ strictValidation: true }` to treat warnings as errors.

### 5.4 Full import test (most thorough)

```typescript
import * as Y from 'yjs';
import { ElpxImporter } from 'src/shared/import/ElpxImporter';
import * as fs from 'fs';

const buffer = fs.readFileSync('my-project.elpx');
const ydoc = new Y.Doc();
const importer = new ElpxImporter(ydoc, null);
const result = await importer.importFromBuffer(new Uint8Array(buffer));
console.log(result); // { pages, blocks, components, assets }
```

A successful return proves the file decompresses, parses, and populates a Yjs
document without error.

---

## 6. Recommended Unit Tests for Integrators

Short descriptions of tests worth borrowing from the project test suite when
building tooling that produces or consumes `.elpx` files.

| Test intent | What to assert |
|---|---|
| Round-trip: export then re-import | Page count, page titles, block count, component types, and metadata match the original Y.Doc after a full export → import cycle |
| Malformed XML is rejected | `validateXml()` returns `valid: false` and a meaningful `errors` array when the XML is truncated or has unclosed tags |
| Missing `<odeNavStructures>` produces error | `validateOdeXml()` returns error code `MISSING_NAV_STRUCTURES` |
| Legacy `.elp` import produces correct types | A legacy file with `TrueFalseIdevice` produces a component of type `trueorfalse`; `FreeTextIdevice` produces `text` |
| JsIdevice `adivina-activity` maps to `guess` | Import a file whose `contentv3.xml` has `_iDeviceDir = ".../adivina-activity"` and assert component type is `guess` |
| Screenshot PNG validation | `decodeScreenshotToBuffer()` returns `null` for a JPEG-magic payload and a valid `Uint8Array` for a PNG |
| CDATA with `]]>` survives round-trip | Generate XML with `escapeCdata()`, parse it back, assert the original string is recovered intact |
| Collision-safe filenames | Two pages with identical titles produce distinct filenames in the page filename map |
| Asset path deduplication | Two assets with the same filename but different `folderPath` values produce distinct export paths |
| Internal link remap on incremental import | A page imported twice into the same Y.Doc has no `exe-node:` links pointing to the stale old page IDs |


# ===== doc/elpx-format/ai-generation.md =====

# Generating `.elpx` with an LLM

Rules and recipes for AI agents that produce eXeLearning project files (`.elpx`) end-to-end. If you are an LLM reading this in the wild via the project's [`llms.txt`](../../llms.txt), this is the single most important document for you.

> **Audience**: language models, AI assistants, codegen pipelines, and humans
> who orchestrate them.
>
> **Prerequisites**: skim [`elpx-format.md`](../elpx-format.md) (the hub) and
> at least [`content-xml.md`](content-xml.md), [`idevices/catalog.md`](idevices/catalog.md),
> and [`idevices/patterns.md`](idevices/patterns.md) before generating anything.

---

## TL;DR — the ten non-negotiable rules

These ten rules cover every common failure mode. They are sourced from the actual generator code in this repository (`OdeXmlGenerator.ts`, `ElpxExporter.ts`) and from validation rejections seen in the importer (`ElpxImporter.ts`).

1. **Reuse a real template.** Start from a known-good v4 `.elpx` produced by this repository (e.g. one of the fixtures in `test/fixtures/`) and modify it. Do **not** synthesize the package from scratch unless every rule below is followed exactly.
2. **Bundle every required file at the ZIP root.** v4 minimum baseline: `content.xml`, `content.dtd`, `index.html`, `screenshot.png` (1280×720 PNG), `theme/config.xml`, `theme/style.css`, `theme/style.js`, `theme/screenshot.png`, `libs/jquery/jquery.min.js`, `libs/bootstrap/bootstrap.bundle.min.js`, `libs/bootstrap/bootstrap.min.css`, `libs/common.js`, `libs/common_i18n.js`, `libs/exe_export.js`, `libs/favicon.ico`, plus per-iDevice JS/CSS in `idevices/<type>/`. Project assets go flat under `content/resources/<filename>` — no UUID subfolders. See [container.md](container.md), [libraries.md](libraries.md), and [assets.md](assets.md) for the full inventory.
3. **Always emit `<odeComponentsProperties>` — even when empty.** The DTD marks it optional, but every fixture and the generator emit it, and downstream tools assume it. When you have no properties, write `<odeComponentsProperties><odeComponentsProperty><key>visibility</key><value>true</value></odeComponentsProperty></odeComponentsProperties>`.
4. **Synchronize redundant IDs.** Inside an `<odeComponent>`, the `<odePageId>` and `<odeBlockId>` MUST equal the IDs of the enclosing `<odePagStructure>` and `<odeNavStructure>`. Inside an `<odePagStructure>`, `<odePageId>` MUST equal the page's own `<odePageId>`. Mismatches reject the component or attach it to the wrong block.
5. **Wrap `<htmlView>` and `<jsonProperties>` in `<![CDATA[ ... ]]>` always.** This is what [`OdeXmlGenerator.ts:270, 275`](../../src/shared/export/generators/OdeXmlGenerator.ts) does, regardless of whether the content has special characters.
6. **Split `]]>` inside CDATA.** When user content contains the literal sequence `]]>`, replace it with `]]]]><![CDATA[>`. The exporter's `escapeCdata` helper does this at [`OdeXmlGenerator.ts:355`](../../src/shared/export/generators/OdeXmlGenerator.ts).
7. **Match the iDevice type to its storage pattern.** Each iDevice type uses one of four content-storage patterns (Standard JSON / URI-encoded JSON / `<script type="application/json">` / `htmlView`-only). Read [`idevices/patterns.md`](idevices/patterns.md) and pick the right one. A `text` iDevice with no `<jsonProperties>` will not be re-editable. A `rubric` with raw JSON inside `<jsonProperties>` instead of URI-encoded JSON inside `<htmlView>` will fail to render.
8. **Use only canonical iDevice type names.** Read the list at [`idevices/catalog.md`](idevices/catalog.md). The XSD `ideviceTypeType` enumeration at [`ode-content.xsd:158-235`](../../public/app/schemas/ode/ode-content.xsd) is the authoritative set. Legacy CamelCase aliases (e.g. `FreeTextIdevice`) are accepted on import but normalized — emit the modern name (e.g. `text`).
9. **Use the `YYYYMMDDHHmmss` + 6 alphanumerics ID format.** All ODE identifiers (`odeId`, `odeVersionId`, `odePageId`, `odeBlockId`, `odeIdeviceId`) follow `[0-9]{14}[A-Z0-9]{6}`. The XSD enforces this regex. Generate IDs with the algorithm in [`OdeXmlGenerator.generateOdeId()`](../../src/shared/export/generators/OdeXmlGenerator.ts) at lines 315-332.
10. **Math markup must use `\(...\)` and `\[...\]`.** Never `$...$` or `$$...$$`. The MathJax bundle this project ships only triggers on the backslash-paren syntax (see [`constants.ts:228`](../../src/shared/export/constants.ts) — pattern `/\\\(|\\\[/`). Use the inline form `\(x^2\)` for inline math, `\[ x = \tfrac{-b \pm \sqrt{b^2-4ac}}{2a} \]` for displays.

---

## Recommended generation pipeline

A robust LLM pipeline for `.elpx` looks like four stages. Each stage has a single responsibility and a verifiable output.

```
  ┌─────────────────┐    ┌──────────────────┐    ┌────────────────┐    ┌──────────────────┐
  │ 1. Pedagogical  │ →  │ 2. Project-shape │ →  │ 3. content.xml │ →  │ 4. ZIP package   │
  │    plan (text)  │    │    JSON (struct) │    │   + DTD + HTML │    │   (.elpx file)   │
  └─────────────────┘    └──────────────────┘    └────────────────┘    └──────────────────┘
       narrative              structured             snippet-driven         deterministic
       per topic              per page/block         per iDevice type       file packing
```

### Stage 1 — Pedagogical plan

Input: a learning objective, a topic, a target audience, a duration.
Output: a Markdown plan listing the pages, the blocks per page, and the iDevice types you intend to use, with one paragraph of pedagogical justification per page.

This stage is purely textual. The LLM does not emit any XML or JSON yet. It does pick iDevice types from [`idevices/catalog.md`](idevices/catalog.md) — and only from that list.

### Stage 2 — Project-shape JSON

Input: the Stage 1 plan.
Output: a structured JSON document describing the entire project tree: title, language, license, theme, and a flat list of pages with their parent-child relationships, blocks, and components. Use a simple JSON shape such as:

```jsonc
{
  "metadata": {
    "title": "An Introduction to Photosynthesis",
    "author": "Jane Doe",
    "language": "en",
    "license": "creative commons: attribution - share alike 4.0",
    "theme": "base",
    "addAccessibilityToolbar": true,
    "addSearchBox": true,
    "addExeLink": true,
    "addPagination": false,
    "addMathJax": false
  },
  "pages": [
    {
      "id": "20251217062007PAGE01",
      "parentId": null,
      "title": "Introduction",
      "order": 0,
      "blocks": [
        {
          "id": "20251217062007BLK001",
          "name": "Text",
          "order": 0,
          "components": [
            {
              "id": "20251217062007IDEV1",
              "type": "text",
              "order": 0,
              "content": { "textTextarea": "<p>Photosynthesis is …</p>" }
            }
          ]
        }
      ]
    },
    {
      "id": "20251217062007PAGE02",
      "parentId": "20251217062007PAGE01",
      "title": "Quick Quiz",
      "order": 1,
      "blocks": [ /* ... */ ]
    }
  ]
}
```

Keep this representation simple. It is intermediate fuel for Stage 3, not the final XML.

### Stage 3 — `content.xml` from snippets

Input: the Stage 2 JSON + the canonical XML snippets in [`idevices/snippets.md`](idevices/snippets.md).
Output: a complete `content.xml` valid against [`content.dtd`](../../public/app/schemas/ode/content.dtd).

Algorithm:

1. Open the document with the prologue from [`content-xml.md`](content-xml.md): XML declaration, DOCTYPE, `<ode>` opening tag.
2. Emit `<userPreferences>` with a single `<userPreference>` for `theme`.
3. Emit `<odeResources>` with three `<odeResource>` entries: `odeId`, `odeVersionId`, `exe_version`. Generate IDs with the format `[0-9]{14}[A-Z0-9]{6}`.
4. Emit `<odeProperties>` with one `<odeProperty>` per metadata key. Use the XML keys from [`metadata.md`](metadata.md) (e.g. `pp_title`, `pp_lang`, `pp_addAccessibilityToolbar`). Booleans become the literal strings `"true"` or `"false"`.
5. Emit `<odeNavStructures>`. For each page in the JSON:
    - Emit `<odeNavStructure>` with `<odePageId>`, `<odeParentPageId>` (empty if root), `<pageName>`, `<odeNavStructureOrder>`.
    - Emit `<odeNavStructureProperties>` with at minimum a `<key>titlePage</key><value>…</value>` entry.
    - Emit `<odePagStructures>` containing one `<odePagStructure>` per block.
    - For each block: emit redundant `<odePageId>`, then `<odeBlockId>`, `<blockName>`, `<iconName/>`, `<odePagStructureOrder>`, `<odePagStructureProperties>`, `<odeComponents>`.
    - For each component: pull the matching XML snippet from [`idevices/snippets.md`](idevices/snippets.md), substitute the IDs, and inject the user content.
6. Close `<odeNavStructures>`, `<ode>`.

Snippet substitution rules per pattern:

| Pattern | Where to inject content | How to encode |
|---------|-------------------------|---------------|
| Standard JSON | `<jsonProperties><![CDATA[ JSON ]]></jsonProperties>` and the rendered HTML in `<htmlView><![CDATA[ HTML ]]></htmlView>`. Both must be semantically aligned. | JSON.stringify; CDATA-wrap; split `]]>`. |
| URI-encoded JSON | Inside the `*-DataGame js-hidden` `<div>` in `<htmlView>`. `<jsonProperties>` empty or omitted. | `encodeURIComponent(JSON.stringify(...))`. |
| `<script type="application/json">` | Inside `<htmlView>`, in a `<script id="exe-…">` tag. | JSON.stringify; do not URL-encode. |
| `htmlView`-only (UDL) | Multiple `<article>` blocks in `<htmlView>`; no JSON state. | Plain HTML; CDATA-wrap; split `]]>`. |

### Stage 4 — ZIP packaging

Input: `content.xml` + a template directory with all the static assets (`content.dtd`, `index.html`, `html/`, `content/`, `libs/`, `theme/`, `idevices/`).
Output: a `.zip` archive renamed to `.elpx`.

Algorithm:

1. Take a known-good template directory (extract one of the project's fixtures, or reuse a previous successful export).
2. Replace `content.xml` with your generated XML.
3. Update `index.html` and any `html/<page>.html` files if you regenerated them (optional — see "skip HTML pre-rendering" below).
4. Drop a `screenshot.png` at the ZIP root if you have one (PNG, recommended 1280×720).
5. ZIP with the standard `deflate` compressor (`zip -r out.elpx .` works).
6. Verify the archive with `unzip -l` and check that `content.xml`, `content.dtd`, `index.html`, `theme/`, `libs/`, `idevices/` are all present.

> **Skip HTML pre-rendering**: an `.elpx` is technically valid for re-import even
> if `index.html` and `html/*.html` are stub or missing — the importer reads
> `content.xml` and reconstructs everything else. Skipping pre-rendering is the
> simplest way for an LLM to produce an `.elpx`. The cost is that the package
> is not viewable offline before re-importing into eXeLearning. For a fully
> portable package, run the project's HTML5 exporter (or a copy of `index.html`
> from a template) to produce the `html/` directory.

---

## Pre-flight checklist (before declaring done)

Run through this list every time you generate an `.elpx`. Anything that fails MUST be fixed before claiming success.

### XML correctness

- [ ] `content.xml` starts with `<?xml version="1.0" encoding="UTF-8"?>`.
- [ ] DOCTYPE line is `<!DOCTYPE ode SYSTEM "content.dtd">`.
- [ ] Root element opens as `<ode xmlns="http://www.intef.es/xsd/ode" version="2.0">`.
- [ ] Top-level children appear in this exact order: `<userPreferences>`, `<odeResources>`, `<odeProperties>`, `<odeNavStructures>`.
- [ ] `<odeNavStructures>` is present and contains at least one `<odeNavStructure>`.
- [ ] DTD validation passes: `xmllint --noout --dtdvalid content.dtd content.xml` (run inside the unzipped directory).
- [ ] XSD validation passes (recommended): `xmllint --noout --schema public/app/schemas/ode/ode-content.xsd content.xml`.

### IDs

- [ ] Every `odeId`, `odeVersionId`, `odePageId`, `odeBlockId`, `odeIdeviceId` matches `[0-9]{14}[A-Z0-9]{6}` (14 digits + 6 chars from `[A-Z0-9]`).
- [ ] All page/block/component IDs are unique within the document.
- [ ] Inside every `<odeComponent>`, `<odePageId>` matches the enclosing page and `<odeBlockId>` matches the enclosing block.
- [ ] Inside every `<odePagStructure>`, `<odePageId>` matches the enclosing page.
- [ ] `<odeParentPageId>` is empty for root pages and references a real `<odePageId>` otherwise.

### Content

- [ ] Every iDevice type used is in the catalog at [`idevices/catalog.md`](idevices/catalog.md).
- [ ] Every iDevice uses the correct content pattern from [`idevices/patterns.md`](idevices/patterns.md).
- [ ] `<htmlView>` and `<jsonProperties>` are CDATA-wrapped.
- [ ] No literal `]]>` appears inside CDATA (use the `]]]]><![CDATA[>` split).
- [ ] No leftover placeholders (`__PLACEHOLDER__`, `UUID-PAGE`, `UUID-BLOQUE`, `<TODO>`, etc.) in any text content.
- [ ] `{{context_path}}` is used only inside `<htmlView>` and `<jsonProperties>` for asset URLs (see [assets.md](assets.md)). Never in a stand-alone `pp_*` property value.
- [ ] All `src=` and `href=` references inside `<htmlView>` either resolve to a file in `content/resources/` (within the ZIP) or are absolute external URLs.

### Container

- [ ] ZIP root contains: `content.xml`, `content.dtd`, `index.html`, **`screenshot.png` (1280×720 PNG)**.
- [ ] `screenshot.png` starts with the PNG magic bytes `89 50 4E 47 0D 0A 1A 0A`. If you don't have one, generate it with [`scripts/add-screenshot.ts`](../../scripts/add-screenshot.ts).
- [ ] `theme/` contains `config.xml`, `style.css`, `style.js`, `screenshot.png`, plus any theme assets (icons, fonts).
- [ ] `libs/` contains the BASE_LIBRARIES from [`constants.ts:325`](../../src/shared/export/constants.ts): `jquery/jquery.min.js`, `common_i18n.js`, `common.js`, `exe_export.js`, `bootstrap/bootstrap.bundle.min.js`, `bootstrap/bootstrap.bundle.min.js.map`, `bootstrap/bootstrap.min.css`, `bootstrap/bootstrap.min.css.map`.
- [ ] `idevices/<type>/` exists for each iDevice type used, with the type's `<type>.js`, `<type>.css`, and `<type>.html` files.
- [ ] Project assets live under `content/resources/<folderPath>/<filename>` — assets without a `folderPath` go at the root, user-created folders appear verbatim as subdirectories, and there are **no** legacy v3 per-asset UUID folders (`[0-9]{14}[A-Z0-9]{6}`). XML refs follow the same shape: `{{context_path}}/<filename>` for root assets, `{{context_path}}/<folderPath>/<filename>` for assets inside a folder. If the package was rebuilt from a v3 source, run [`scripts/flatten-elpx.ts`](../../scripts/flatten-elpx.ts) to normalise (it preserves user folders).
- [ ] At least 2 iDevices total in the project. Single-iDevice projects are a useful smell test for AI-generated learning content — they usually indicate the LLM produced a stub instead of a complete pedagogical sequence.

### Round-trip test

- [ ] Open the `.elpx` in eXeLearning. The import succeeds with no warnings.
- [ ] Every page renders correctly in the editor's preview.
- [ ] Every iDevice can be opened, its content matches what the LLM generated, and saving leaves the project re-exportable.

---

## Common rejection causes (and how to fix them)

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Importer shows "0 pages imported" | `<odeNavStructures>` is empty or out of order | Ensure at least one `<odeNavStructure>` and that the four top-level children appear in declared order. |
| One page is missing in the navigation tree | `<odeParentPageId>` references a non-existent page ID | Make sure parent IDs match a real `<odePageId>` elsewhere in the document. |
| iDevice renders as a blank box | `<htmlView>` is empty or `<jsonProperties>` is malformed JSON | Keep both fields semantically aligned; validate the JSON with `JSON.parse()` before embedding. |
| "Cannot re-edit this iDevice" in the editor | `<jsonProperties>` is missing for a Standard-JSON iDevice | Always emit `<jsonProperties>` for `text`, `casestudy`, `quick-questions*`, `trueorfalse`, `form`, `image-gallery`, `magnifier`, `external-website`, `download-source-file`. |
| Game iDevice shows "Loading…" forever | URI-encoded JSON inside the `*-DataGame js-hidden` div is missing or not URL-encoded | Apply `encodeURIComponent(JSON.stringify(state))` and place the result in the hidden div. |
| MathJax is not rendering equations | Used `$…$` syntax, or `pp_addMathJax` is `"false"` | Use `\(…\)` for inline and `\[…\]` for displays; set `pp_addMathJax=true` in `<odeProperties>`. |
| XML parse error: unexpected end of CDATA | Content contained literal `]]>` | Apply the `]]]]><![CDATA[>` split. |
| XSD validation fails: `cvc-pattern-valid` on an ID | ID format does not match `[0-9]{14}[A-Z0-9]{6}` | Generate IDs with the canonical algorithm: `<14-digit timestamp><6 random A-Z0-9>`. |
| Importer logs "unknown iDevice type" | Used a deprecated CamelCase or invented name | Use the modern name from [`idevices/catalog.md`](idevices/catalog.md). |
| Image tag in `<htmlView>` shows broken icon | Asset URL points to `asset://…` or to a missing file | Use `{{context_path}}/content/resources/<filename>` and ensure `<filename>` exists inside the ZIP. |

---

## Prompt-engineering hints (for orchestrators)

If you are designing a prompt for an LLM that will execute Stage 3 (XML emission), the following constraints should appear in the system prompt:

1. **Output is XML only.** No prose, no Markdown fences, no explanatory text. The LLM must emit a single XML document and stop.
2. **Use the snippet library.** Pre-load [`idevices/snippets.md`](idevices/snippets.md) as context. The LLM picks the snippet for the iDevice type, substitutes IDs, and injects user content.
3. **Treat IDs as opaque tokens.** Pre-generate every ODE identifier in the orchestrator (not in the LLM) and pass them in. LLMs are bad at producing 20-character random strings reliably.
4. **Never invent iDevice types.** If the requested type is not in the catalog, fall back to `text` and embed the requested behavior as static HTML.
5. **Constrain content size.** Per-iDevice JSON should stay under ~10 KB. Long passages are fine in `textTextarea` as long as they are valid HTML.
6. **Validate before emitting.** Before returning the XML, the orchestrator should run `xmllint --noout --dtdvalid` against the bundled DTD; if it fails, regenerate Stage 3 with the parser error appended to the prompt.

A reasonable system prompt skeleton:

```
You are an XML emitter for eXeLearning .elpx packages. Given a JSON
description of a project, produce a single content.xml document valid
against the bundled content.dtd.

Rules:
- Emit only XML. No explanation.
- Use only the iDevice types in the provided catalog.
- Wrap <htmlView> and <jsonProperties> in <![CDATA[ ... ]]>.
- Replace any literal "]]>" in content with "]]]]><![CDATA[>".
- Use these IDs verbatim: <ID list provided by the orchestrator>.
- Boolean property values are the literal strings "true" / "false".
- Math expressions use \(...\) for inline and \[...\] for display.

Snippets:
<paste idevices/snippets.md or the relevant subset>

Project JSON:
<the Stage 2 JSON>

Now emit content.xml.
```

---

## See also

- [`elpx-format.md`](../elpx-format.md) — hub
- [`content-xml.md`](content-xml.md) — full XML reference
- [`idevices/catalog.md`](idevices/catalog.md) — every supported type
- [`idevices/patterns.md`](idevices/patterns.md) — the four content-storage patterns
- [`idevices/snippets.md`](idevices/snippets.md) — copy-pasteable XML per type
- [`validation.md`](validation.md) — DTD/XSD validation playbook
- [`examples/minimal-content-xml.md`](examples/minimal-content-xml.md) — smallest valid example
- [`/llms.txt`](../../llms.txt) — top-level index for LLM consumption


# ===== doc/elpx-format/examples/minimal-content-xml.md =====

# Minimal content.xml

This is the smallest valid `content.xml` you can write: one root page, one block, one `text`
iDevice. Every element shown here is required — remove any of them and the importer will either
reject the file or silently drop content.

The generator that produces this XML is `src/shared/export/generators/OdeXmlGenerator.ts`.
The full element reference lives in [../content-xml.md](../content-xml.md). For iDevice-specific
HTML and JSON shapes see [../idevices/snippets.md](../idevices/snippets.md).

To turn this `content.xml` into a working `.elpx`, wrap it in a ZIP — see the recipe at the end
of this page.

---

## The complete XML

The listing below is annotated with inline comments. Every element and attribute is mandatory
unless a comment says otherwise.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- Processing instruction: XML 1.0, UTF-8. The generator always writes this first line. -->

<!DOCTYPE ode SYSTEM "content.dtd">
<!-- DTD declaration. The filename "content.dtd" is the value of the ODE_DTD_FILENAME constant
     (src/shared/export/constants.ts). The DTD file must exist at the same path inside the ZIP.
     Omit this line only for IMS/SCORM exports where no DTD is bundled. -->

<ode xmlns="http://www.intef.es/xsd/ode" version="2.0">
  <!-- Root element. xmlns and version are fixed values; do not change them. -->

  <!-- ═══════════════════════════════════════════════════════════════════════
       SECTION 1: userPreferences
       User-level settings stored with the document.  Currently only "theme"
       is written.  The value is the folder name under the bundled themes
       directory; "base" is the default theme shipped with eXeLearning.
       ═══════════════════════════════════════════════════════════════════════ -->
  <userPreferences>
    <userPreference>
      <key>theme</key>
      <value>base</value>
      <!-- Other possible values: "lernmodule", "formal_darkgray", or any custom theme name. -->
    </userPreference>
  </userPreferences>

  <!-- ═══════════════════════════════════════════════════════════════════════
       SECTION 2: odeResources
       Three entries are always written by the generator (generateOdeResourcesXml).
       The key names are exact — "exe_version" is correct, NOT "eXeVersion".
       ═══════════════════════════════════════════════════════════════════════ -->
  <odeResources>
    <odeResource>
      <key>odeId</key>
      <value>20251217061325ABC001</value>
      <!-- Stable project identifier: YYYYMMDDHHmmss + 6 uppercase alphanumeric chars.
           Generated once when the project is first created; never changes on re-save. -->
    </odeResource>
    <odeResource>
      <key>odeVersionId</key>
      <value>20251217062007XYZ002</value>
      <!-- Version identifier: same format as odeId, generated fresh on every export.
           Two exports of the same project will have different odeVersionId values. -->
    </odeResource>
    <odeResource>
      <key>exe_version</key>
      <value>3.0</value>
      <!-- The ODE_VERSION constant from src/shared/export/constants.ts.
           NOTE: this key is "exe_version" (lowercase, underscore), not "eXeVersion".
           Legacy files from pre-v4 eXeLearning may use "eXeVersion" — the importer
           handles both, but the generator always writes "exe_version". -->
    </odeResource>
  </odeResources>

  <!-- ═══════════════════════════════════════════════════════════════════════
       SECTION 3: odeProperties
       Project-level metadata.  Each entry is an <odeProperty> key/value pair.
       The generator iterates ExportMetadata, skipping null/empty/excluded fields.
       Only the most common keys are shown here; see content-xml.md for the full list.
       ═══════════════════════════════════════════════════════════════════════ -->
  <odeProperties>
    <odeProperty>
      <key>pp_title</key>
      <value>My First eXeLearning Project</value>
      <!-- Human-readable title shown in the exported HTML page <title> tag. -->
    </odeProperty>
    <odeProperty>
      <key>pp_lang</key>
      <value>en</value>
      <!-- BCP-47 language tag.  Used for the HTML lang attribute and accessibility. -->
    </odeProperty>
    <odeProperty>
      <key>pp_author</key>
      <value>Jane Educator</value>
      <!-- Author name, written to <meta name="author"> in exported HTML. -->
    </odeProperty>
    <odeProperty>
      <key>pp_addExeLink</key>
      <value>true</value>
      <!-- When true, a "Made with eXeLearning" footer link is injected into exports.
           Boolean values are written as the strings "true" or "false". -->
    </odeProperty>
  </odeProperties>

  <!-- ═══════════════════════════════════════════════════════════════════════
       SECTION 4: odeNavStructures
       One <odeNavStructure> element per page, in tree order (parent before children).
       This minimal example has exactly one root page.
       ═══════════════════════════════════════════════════════════════════════ -->
  <odeNavStructures>

    <odeNavStructure>
      <!-- ── Page identity ── -->
      <odePageId>20251217062007PAGE01</odePageId>
      <!-- Unique page identifier.  Same format as odeId. -->

      <odeParentPageId></odeParentPageId>
      <!-- Empty string means this is a root page (no parent).
           Child pages set this to the parent's <odePageId>. -->

      <pageName>Introduction</pageName>
      <!-- Navigation label shown in the left-hand page tree. -->

      <odeNavStructureOrder>1</odeNavStructureOrder>
      <!-- 1-based position among siblings.  Root pages are ordered relative to each other. -->

      <!-- ── Page-level properties ── -->
      <odeNavStructureProperties>
        <odeNavStructureProperty>
          <key>titlePage</key>
          <value>Introduction</value>
          <!-- Page heading rendered as <h1> at the top of the page body. -->
        </odeNavStructureProperty>
        <!-- Additional optional properties: hidePageTitle, editableInPage, highlight, description.
             They are written by the generator when non-default values are set. -->
      </odeNavStructureProperties>

      <!-- ── Blocks (odePagStructures) ── -->
      <!-- Each block is a collapsible container for one or more iDevices. -->
      <odePagStructures>

        <odePagStructure>
          <!-- ── Block identity ── -->
          <odePageId>20251217062007PAGE01</odePageId>
          <!-- Repeats the parent page id — the importer uses this to associate
               blocks with pages even when parsing a flat list of elements. -->

          <odeBlockId>20251217062007BLK001</odeBlockId>
          <!-- Unique block identifier within the project. -->

          <blockName>Text block</blockName>
          <!-- Displayed in the block header when the block is collapsed. -->

          <iconName></iconName>
          <!-- Optional icon name for the block header.  Empty string is valid. -->

          <odePagStructureOrder>1</odePagStructureOrder>
          <!-- 1-based position of this block within the page. -->

          <!-- ── Block-level properties ── -->
          <odePagStructureProperties>
            <odePagStructureProperty>
              <key>visibility</key>
              <value>true</value>
              <!-- Whether the block is visible to students.  "true" or "false". -->
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>teacherOnly</key>
              <value>false</value>
              <!-- When true, block is hidden from learners and shown only in teacher view. -->
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>allowToggle</key>
              <value>true</value>
              <!-- When true, learners can collapse/expand the block. -->
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>minimized</key>
              <value>false</value>
              <!-- Initial collapsed state.  Usually false. -->
            </odePagStructureProperty>
          </odePagStructureProperties>

          <!-- ── Components (iDevices) ── -->
          <odeComponents>

            <odeComponent>
              <!-- ── Component identity ── -->
              <odePageId>20251217062007PAGE01</odePageId>
              <!-- Repeats the parent page id (same pattern as block ↔ page). -->

              <odeBlockId>20251217062007BLK001</odeBlockId>
              <!-- Repeats the parent block id. -->

              <odeIdeviceId>20251217062007IDEV01</odeIdeviceId>
              <!-- Unique iDevice identifier.  Used in the asset record's referencedBy
                   list and in any `data-asset-id` attribute that links a DOM node to
                   this iDevice.  iDevice file assets do NOT live in a per-iDevice
                   subfolder — they go under content/resources/<filename> (or
                   content/resources/<folderPath>/<filename> when the user organised
                   them into folders via the file manager).  See ../assets.md. -->

              <odeIdeviceTypeName>text</odeIdeviceTypeName>
              <!-- Registered iDevice type name.  Must match the "name" field in the
                   iDevice's config.xml.  Common values: "text", "interactive-video",
                   "rubric", "udl-content".  See ../idevices/snippets.md for more. -->

              <!-- ── Rendered HTML (always CDATA-wrapped) ── -->
              <htmlView><![CDATA[<div class="exe-text-template"><div class="textIdeviceContent">
  <div class="exe-text-activity">
    <div>
      <p>Welcome to your first eXeLearning project. This paragraph was typed
         into the <strong>Text</strong> iDevice editor.</p>
    </div>
  </div>
</div></div>]]></htmlView>
              <!-- The rendered HTML that the export engine places directly in page HTML.
                   CDATA wrapping is unconditional — even if the content contains no
                   characters that require escaping, the generator always writes CDATA.
                   This matches lines 269-270 of OdeXmlGenerator.ts. -->

              <!-- ── JSON properties (always CDATA-wrapped) ── -->
              <jsonProperties><![CDATA[{"ideviceId":"20251217062007IDEV01","textTextarea":"<p>Welcome to your first eXeLearning project. This paragraph was typed into the <strong>Text</strong> iDevice editor.</p>","textFeedbackInput":"Show Feedback","textFeedbackTextarea":"","textInfoDurationInput":"","textInfoDurationTextInput":"Duration","textInfoParticipantsInput":"","textInfoParticipantsTextInput":"Grouping"}]]></jsonProperties>
              <!-- The iDevice's internal state as a JSON object, CDATA-wrapped.
                   This is the authoritative source when re-importing; htmlView is
                   re-generated from jsonProperties during import.
                   NOTE: inside CDATA the JSON is NOT HTML-escaped — angle brackets,
                   quotes, and ampersands are literal characters.
                   If the JSON string itself contains "]]>" it is split across two
                   CDATA sections (see escapeCdata() in OdeXmlGenerator.ts). -->

              <odeComponentsOrder>1</odeComponentsOrder>
              <!-- 1-based position of this component within the block. -->

              <!-- ── Component structural properties ── -->
              <odeComponentsProperties>
                <odeComponentsProperty>
                  <key>visibility</key>
                  <value>true</value>
                  <!-- Mirrors the block-level visibility but at iDevice granularity. -->
                </odeComponentsProperty>
              </odeComponentsProperties>
              <!-- If component.structureProperties is absent, the generator writes
                   visibility=true as a default (OdeXmlGenerator.ts lines 291-293). -->

            </odeComponent>

          </odeComponents>
        </odePagStructure>

      </odePagStructures>
    </odeNavStructure>

  </odeNavStructures>
</ode>
```

---

## What's next

- **Validate** the XML against the bundled DTD — see the command in the section below.
- **Add more pages** and iDevice types — see [multi-page-content-xml.md](multi-page-content-xml.md).
- **Browse iDevice HTML/JSON shapes** — see [../idevices/snippets.md](../idevices/snippets.md).
- **Understand the full element reference** — see [../content-xml.md](../content-xml.md).
- **Understand the ZIP structure** — see [full-package-tree.md](full-package-tree.md) and
  [../container.md](../container.md).

---

## Validating with xmllint

Before importing or shipping a `content.xml`, validate it against the bundled DTD:

```bash
# From the directory that contains both content.xml and content.dtd:
xmllint --noout --dtdvalid content.dtd content.xml && echo "valid"

# If content.dtd is in a different location, point --dtdvalid at its path:
xmllint --noout --dtdvalid /path/to/content.dtd content.xml
```

`xmllint` is part of `libxml2`, available on all major platforms:

```bash
# macOS
brew install libxml2

# Debian / Ubuntu
apt-get install libxml2-utils
```

---

## ZIP it up — making a working .elpx

An `.elpx` is a plain ZIP archive. The **bare-minimum re-importable** layout is just two
files:

```
myproject/
├── content.xml      ← the file above
└── content.dtd      ← copy from public/app/schemas/ode/content.dtd
```

The importer (`ElpxImporter.ts`) does not require anything else. Everything below is
optional from the importer's point of view — but is required for a **publishable v4
package** that is offline-viewable in any browser:

```
myproject/
├── content.xml      ← the file above
├── content.dtd      ← copy from public/app/schemas/ode/content.dtd
├── index.html       ← rendered first page (can be empty <html></html> for a stub)
├── screenshot.png   ← 1280×720 PNG project thumbnail (run scripts/add-screenshot.ts)
├── theme/           ← active theme (config.xml + style.css + style.js + screenshot.png)
├── libs/            ← BASE_LIBRARIES from src/shared/export/constants.ts
├── idevices/<type>/ ← runtime files for each iDevice type referenced in content.xml
└── content/resources/<filename>   ← any project assets (images/audio/PDFs/…),
                                     optionally under a user-created folderPath
```

If `<htmlView>` references a `{{context_path}}/<filename>` (or
`{{context_path}}/<folderPath>/<filename>`), the matching file MUST exist at
`content/resources/<filename>` (or under the same `<folderPath>`). See
[../assets.md](../assets.md) for the URL lifecycle.

Create the ZIP with the standard `zip` command. The archive must **not** include a
top-level `myproject/` directory — entries must be at the root of the ZIP:

```bash
# From inside the myproject/ directory:
cd myproject/

# Re-importable minimum:
zip ../myproject.elpx content.xml content.dtd

# v4 publishable package:
zip -r ../myproject.elpx \
    content.xml content.dtd index.html screenshot.png \
    theme/ libs/ idevices/ content/

mv ../myproject.elpx ../myproject.elpx   # rename if needed
```

Validate before shipping:

```bash
cd myproject/
xmllint --noout --dtdvalid content.dtd content.xml && echo "DTD valid"
```

See [../validation.md](../validation.md) for the full v4 release checklist.

Then open eXeLearning, choose **File → Import** and select `myproject.elpx`. The importer reads
`content.xml` to reconstruct the Yjs document in the browser; it does not parse any HTML files.


# ===== doc/elpx-format/examples/multi-page-content-xml.md =====

# Multi-page content.xml

This example shows a `content.xml` with a three-level hierarchy:

```
Root page (20251217062007PAGE01)
├── Child page A (20251217062007PAGE02)
└── Child page B (20251217062007PAGE03)
```

Each page contains at least one block. Across the three pages the example covers all four
iDevice content-encoding patterns:

| Pattern | iDevice type | Where |
|---------|-------------|-------|
| Standard JSON (htmlView + jsonProperties) | `text` | Page 01, Block 01 |
| URI-encoded game data | `rubric` | Page 02, Block 01 |
| Script-tag JSON | `interactive-video` | Page 02, Block 02 |
| htmlView-only (no jsonProperties) | `udl-content` | Page 03, Block 01 |

The root page also contains an internal cross-page link using the `exe-node:` URI scheme.

Full element reference: [../content-xml.md](../content-xml.md).
iDevice HTML/JSON shapes: [../idevices/snippets.md](../idevices/snippets.md).
Minimal single-iDevice baseline: [minimal-content-xml.md](minimal-content-xml.md).

---

## Document header and metadata

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ode SYSTEM "content.dtd">
<!-- content.dtd filename comes from ODE_DTD_FILENAME in src/shared/export/constants.ts -->

<ode xmlns="http://www.intef.es/xsd/ode" version="2.0">

  <userPreferences>
    <userPreference>
      <key>theme</key>
      <value>base</value>
    </userPreference>
  </userPreferences>

  <odeResources>
    <odeResource>
      <key>odeId</key>
      <value>20251217062007MULPG1</value>
      <!-- Stable project ID: generated once, never changes on re-save. -->
    </odeResource>
    <odeResource>
      <key>odeVersionId</key>
      <value>20251217062007MULPG2</value>
      <!-- Fresh on every export. -->
    </odeResource>
    <odeResource>
      <key>exe_version</key>
      <value>3.0</value>
      <!-- Key is "exe_version" (underscore, lowercase) — not "eXeVersion". -->
    </odeResource>
  </odeResources>

  <odeProperties>
    <odeProperty>
      <key>pp_title</key>
      <value>Multi-page Example</value>
    </odeProperty>
    <odeProperty>
      <key>pp_lang</key>
      <value>en</value>
    </odeProperty>
    <odeProperty>
      <key>pp_author</key>
      <value>Jane Educator</value>
    </odeProperty>
    <odeProperty>
      <key>pp_addExeLink</key>
      <value>true</value>
    </odeProperty>
    <odeProperty>
      <key>pp_addPagination</key>
      <value>true</value>
      <!-- Enables previous/next navigation buttons in the exported HTML. -->
    </odeProperty>
    <odeProperty>
      <key>pp_addSearchBox</key>
      <value>true</value>
    </odeProperty>
  </odeProperties>

  <odeNavStructures>
```

---

## Page 01 — root page with a text iDevice and a cross-page link

Page 01 is a root page (`<odeParentPageId>` is empty). Its single block holds one `text`
iDevice whose `<htmlView>` contains an `exe-node:` link pointing at the child page PAGE02.

The `text` iDevice uses **Pattern 1 (standard JSON)**: the full editor state is stored in
`<jsonProperties>` as a plain JSON object wrapped in CDATA, and `<htmlView>` holds the
rendered HTML also wrapped in CDATA.

```xml
    <!-- ══════════════════════════════════════════════════════════════
         PAGE 01 — root page
         ══════════════════════════════════════════════════════════════ -->
    <odeNavStructure>
      <odePageId>20251217062007PAGE01</odePageId>
      <odeParentPageId></odeParentPageId>
      <!-- Empty odeParentPageId marks a root-level page. -->
      <pageName>Overview</pageName>
      <odeNavStructureOrder>1</odeNavStructureOrder>

      <odeNavStructureProperties>
        <odeNavStructureProperty>
          <key>titlePage</key>
          <value>Overview</value>
        </odeNavStructureProperty>
        <odeNavStructureProperty>
          <key>hidePageTitle</key>
          <value>false</value>
        </odeNavStructureProperty>
        <odeNavStructureProperty>
          <key>visibility</key>
          <value>true</value>
        </odeNavStructureProperty>
      </odeNavStructureProperties>

      <odePagStructures>

        <!-- Block 01 on page 01 -->
        <odePagStructure>
          <odePageId>20251217062007PAGE01</odePageId>
          <odeBlockId>20251217062007BLK01</odeBlockId>
          <blockName>Introduction</blockName>
          <iconName></iconName>
          <odePagStructureOrder>1</odePagStructureOrder>

          <odePagStructureProperties>
            <odePagStructureProperty>
              <key>visibility</key>
              <value>true</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>teacherOnly</key>
              <value>false</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>allowToggle</key>
              <value>true</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>minimized</key>
              <value>false</value>
            </odePagStructureProperty>
          </odePagStructureProperties>

          <odeComponents>

            <!-- ── iDevice: text (Pattern 1 — standard JSON) ──────────────
                 Both <htmlView> and <jsonProperties> are present and both are
                 unconditionally wrapped in CDATA regardless of content.
                 The htmlView is what the HTML exporter inlines; the jsonProperties
                 is the source of truth used by the importer to restore editor state.
                 ─────────────────────────────────────────────────────────────── -->
            <odeComponent>
              <odePageId>20251217062007PAGE01</odePageId>
              <odeBlockId>20251217062007BLK01</odeBlockId>
              <odeIdeviceId>20251217062007IDEV1</odeIdeviceId>
              <odeIdeviceTypeName>text</odeIdeviceTypeName>

              <htmlView><![CDATA[<div class="exe-text-template"><div class="textIdeviceContent">
  <div class="exe-text-activity">
    <div>
      <p>This module covers three topics. Start with
         <a href="exe-node:20251217062007PAGE02">Topic A</a>
         or jump straight to
         <a href="exe-node:20251217062007PAGE03">Topic B</a>.</p>
    </div>
  </div>
</div></div>]]></htmlView>
              <!-- exe-node:<pageId> is an internal cross-page link.
                   The HTML exporter rewrites these to relative paths (e.g. html/page-2.html)
                   at export time.  Inside content.xml they are always stored as exe-node: URIs
                   so that the link survives page reordering or renaming. -->

              <jsonProperties><![CDATA[{"ideviceId":"20251217062007IDEV1","textTextarea":"<p>This module covers three topics. Start with <a href=\"exe-node:20251217062007PAGE02\">Topic A</a> or jump straight to <a href=\"exe-node:20251217062007PAGE03\">Topic B</a>.</p>","textFeedbackInput":"Show Feedback","textFeedbackTextarea":"","textInfoDurationInput":"","textInfoDurationTextInput":"Duration","textInfoParticipantsInput":"","textInfoParticipantsTextInput":"Grouping"}]]></jsonProperties>
              <!-- Inside the CDATA block JSON is stored as literal characters.
                   The JSON value of textTextarea contains HTML with double-quoted attributes;
                   those quotes are JSON-escaped (\") inside the JSON string but are NOT
                   XML-escaped because CDATA does not require XML escaping. -->

              <odeComponentsOrder>1</odeComponentsOrder>
              <odeComponentsProperties>
                <odeComponentsProperty>
                  <key>visibility</key>
                  <value>true</value>
                </odeComponentsProperty>
              </odeComponentsProperties>
            </odeComponent>

          </odeComponents>
        </odePagStructure>

      </odePagStructures>
    </odeNavStructure>
```

---

## Page 02 — child of Page 01, with a game iDevice and an interactive-video iDevice

Page 02 is a child of PAGE01. It has two blocks: a `rubric` game iDevice (Pattern 2,
URI-encoded) and an `interactive-video` iDevice (Pattern 3, script-tag JSON).

### Pattern 2 — URI-encoded game data (`rubric`)

The `rubric` iDevice stores its game configuration as a URI-encoded JSON string inside a
`<div class="exe-rubrics-DataGame js-hidden">` element in `<htmlView>`. The
`<jsonProperties>` holds the normal editor-state JSON. The game engine initialises itself by
reading and decoding that hidden div at runtime.

URI encoding is used because the game data can be large and may contain characters (curly
braces, colons, quotes) that would interfere with naive string handling in older browsers.

### Pattern 3 — script-tag JSON (`interactive-video`)

The `interactive-video` iDevice stores its configuration as an inline `<script>` tag with
`type="application/json"` inside `<htmlView>`. This avoids URI-encoding overhead for large
video annotation objects and gives the runtime direct access to a parsed JSON structure.

```xml
    <!-- ══════════════════════════════════════════════════════════════
         PAGE 02 — child of PAGE01 (Topic A)
         ══════════════════════════════════════════════════════════════ -->
    <odeNavStructure>
      <odePageId>20251217062007PAGE02</odePageId>
      <odeParentPageId>20251217062007PAGE01</odeParentPageId>
      <!-- odeParentPageId matches PAGE01's odePageId — this makes PAGE02 a child. -->
      <pageName>Topic A</pageName>
      <odeNavStructureOrder>1</odeNavStructureOrder>
      <!-- Order 1 among PAGE01's children. -->

      <odeNavStructureProperties>
        <odeNavStructureProperty>
          <key>titlePage</key>
          <value>Topic A</value>
        </odeNavStructureProperty>
        <odeNavStructureProperty>
          <key>hidePageTitle</key>
          <value>false</value>
        </odeNavStructureProperty>
        <odeNavStructureProperty>
          <key>visibility</key>
          <value>true</value>
        </odeNavStructureProperty>
      </odeNavStructureProperties>

      <odePagStructures>

        <!-- Block 01 on page 02 — rubric game iDevice (Pattern 2: URI-encoded) -->
        <odePagStructure>
          <odePageId>20251217062007PAGE02</odePageId>
          <odeBlockId>20251217062007BLK02</odeBlockId>
          <blockName>Self-assessment rubric</blockName>
          <iconName></iconName>
          <odePagStructureOrder>1</odePagStructureOrder>

          <odePagStructureProperties>
            <odePagStructureProperty>
              <key>visibility</key>
              <value>true</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>teacherOnly</key>
              <value>false</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>allowToggle</key>
              <value>true</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>minimized</key>
              <value>false</value>
            </odePagStructureProperty>
          </odePagStructureProperties>

          <odeComponents>

            <!-- ── iDevice: rubric (Pattern 2 — URI-encoded game data) ───────
                 The htmlView contains the rendered rubric HTML plus a hidden div
                 whose text content is the URI-encoded game configuration JSON.
                 The game bootstrap script reads that div, calls decodeURIComponent(),
                 and parses the resulting JSON to initialise the rubric widget.
                 ─────────────────────────────────────────────────────────────── -->
            <odeComponent>
              <odePageId>20251217062007PAGE02</odePageId>
              <odeBlockId>20251217062007BLK02</odeBlockId>
              <odeIdeviceId>20251217062007IDEV2</odeIdeviceId>
              <odeIdeviceTypeName>rubric</odeIdeviceTypeName>

              <htmlView><![CDATA[<div class="exe-rubric" id="exe-rubric-20251217062007IDEV2">
  <div class="exe-rubrics-DataGame js-hidden">%7B%22id%22%3A%2220251217062007IDEV2%22%2C%22title%22%3A%22Reading%20comprehension%22%2C%22criteria%22%3A%5B%7B%22label%22%3A%22Identifies%20main%20idea%22%2C%22levels%22%3A%5B%22Beginning%22%2C%22Developing%22%2C%22Proficient%22%2C%22Exemplary%22%5D%7D%5D%7D</div>
  <!-- The string above is URI-encoded JSON.  Decoded it equals:
       {"id":"20251217062007IDEV2","title":"Reading comprehension",
        "criteria":[{"label":"Identifies main idea",
                     "levels":["Beginning","Developing","Proficient","Exemplary"]}]}
       The game runtime calls decodeURIComponent() on this div's textContent. -->
  <table class="exe-rubric-table" aria-label="Reading comprehension">
    <thead>
      <tr>
        <th>Criterion</th>
        <th>Beginning</th><th>Developing</th><th>Proficient</th><th>Exemplary</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Identifies main idea</td>
        <td><input type="radio" name="c0" value="0"></td>
        <td><input type="radio" name="c0" value="1"></td>
        <td><input type="radio" name="c0" value="2"></td>
        <td><input type="radio" name="c0" value="3"></td>
      </tr>
    </tbody>
  </table>
</div>]]></htmlView>

              <jsonProperties><![CDATA[{"ideviceId":"20251217062007IDEV2","rubricTitle":"Reading comprehension","rubricCriteria":[{"label":"Identifies main idea","levels":["Beginning","Developing","Proficient","Exemplary"]}]}]]></jsonProperties>
              <!-- jsonProperties holds the plain editor-state JSON used by the importer
                   to restore the rubric form fields.  The game-data div in htmlView is
                   regenerated from this JSON during the next export. -->

              <odeComponentsOrder>1</odeComponentsOrder>
              <odeComponentsProperties>
                <odeComponentsProperty>
                  <key>visibility</key>
                  <value>true</value>
                </odeComponentsProperty>
              </odeComponentsProperties>
            </odeComponent>

          </odeComponents>
        </odePagStructure>

        <!-- Block 02 on page 02 — interactive-video iDevice (Pattern 3: script-tag JSON) -->
        <odePagStructure>
          <odePageId>20251217062007PAGE02</odePageId>
          <odeBlockId>20251217062007BLK03</odeBlockId>
          <blockName>Video with annotations</blockName>
          <iconName></iconName>
          <odePagStructureOrder>2</odePagStructureOrder>

          <odePagStructureProperties>
            <odePagStructureProperty>
              <key>visibility</key>
              <value>true</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>teacherOnly</key>
              <value>false</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>allowToggle</key>
              <value>true</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>minimized</key>
              <value>false</value>
            </odePagStructureProperty>
          </odePagStructureProperties>

          <odeComponents>

            <!-- ── iDevice: interactive-video (Pattern 3 — script-tag JSON) ──
                 The htmlView embeds a <script type="application/json"> element
                 containing the full video configuration.  The widget bootstrap code
                 queries document.querySelector('script[type="application/json"]')
                 within its container and calls JSON.parse() on its textContent.
                 This pattern avoids URI-encoding overhead for large annotation sets.
                 ─────────────────────────────────────────────────────────────── -->
            <odeComponent>
              <odePageId>20251217062007PAGE02</odePageId>
              <odeBlockId>20251217062007BLK03</odeBlockId>
              <odeIdeviceId>20251217062007IDEV3</odeIdeviceId>
              <odeIdeviceTypeName>interactive-video</odeIdeviceTypeName>

              <htmlView><![CDATA[<div class="exe-interactive-video" id="exe-iv-20251217062007IDEV3">
  <script type="application/json">
  {
    "id": "20251217062007IDEV3",
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "annotations": [
      {
        "time": 12,
        "type": "question",
        "text": "What is the main message of this video?"
      },
      {
        "time": 45,
        "type": "note",
        "text": "Pay attention to the visual metaphor used here."
      }
    ]
  }
  </script>
  <!-- The <script type="application/json"> block is inside CDATA in content.xml,
       so the curly braces and quotes are stored as literal characters without any
       XML or URI escaping.  The browser never executes this script tag because its
       type is not "text/javascript". -->
  <div class="exe-iv-player" data-idevice-id="20251217062007IDEV3">
    <div class="exe-iv-video-container"></div>
    <div class="exe-iv-annotations" aria-live="polite"></div>
  </div>
</div>]]></htmlView>

              <jsonProperties><![CDATA[{"ideviceId":"20251217062007IDEV3","ivVideoUrl":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ivAnnotations":[{"time":12,"type":"question","text":"What is the main message of this video?"},{"time":45,"type":"note","text":"Pay attention to the visual metaphor used here."}]}]]></jsonProperties>
              <!-- jsonProperties keys:
                   - ideviceId: matches <odeIdeviceId> above
                   - ivVideoUrl: the video source URL
                   - ivAnnotations: array of timed annotation objects with
                     { time (seconds), type ("question"|"note"|"pause"), text } -->

              <odeComponentsOrder>1</odeComponentsOrder>
              <odeComponentsProperties>
                <odeComponentsProperty>
                  <key>visibility</key>
                  <value>true</value>
                </odeComponentsProperty>
              </odeComponentsProperties>
            </odeComponent>

          </odeComponents>
        </odePagStructure>

      </odePagStructures>
    </odeNavStructure>
```

---

## Page 03 — child of Page 01, with a UDL iDevice (htmlView-only)

Page 03 is the second child of PAGE01. It holds a `udl-content` iDevice that uses
**Pattern 4 (htmlView-only)**: the iDevice stores no `<jsonProperties>` state — the
`<jsonProperties>` element is present but empty. The rendered HTML in `<htmlView>` is both
the display artefact and the persistence mechanism; the importer reads it back as-is.

This pattern is typical for iDevices whose entire state is captured by their HTML output,
such as structured accessibility overlays or static layout blocks.

```xml
    <!-- ══════════════════════════════════════════════════════════════
         PAGE 03 — child of PAGE01 (Topic B)
         ══════════════════════════════════════════════════════════════ -->
    <odeNavStructure>
      <odePageId>20251217062007PAGE03</odePageId>
      <odeParentPageId>20251217062007PAGE01</odeParentPageId>
      <pageName>Topic B</pageName>
      <odeNavStructureOrder>2</odeNavStructureOrder>
      <!-- Order 2 among PAGE01's children — comes after PAGE02. -->

      <odeNavStructureProperties>
        <odeNavStructureProperty>
          <key>titlePage</key>
          <value>Topic B</value>
        </odeNavStructureProperty>
        <odeNavStructureProperty>
          <key>hidePageTitle</key>
          <value>false</value>
        </odeNavStructureProperty>
        <odeNavStructureProperty>
          <key>visibility</key>
          <value>true</value>
        </odeNavStructureProperty>
      </odeNavStructureProperties>

      <odePagStructures>

        <!-- Block 01 on page 03 — udl-content iDevice (Pattern 4: htmlView-only) -->
        <odePagStructure>
          <odePageId>20251217062007PAGE03</odePageId>
          <odeBlockId>20251217062007BLK04</odeBlockId>
          <blockName>UDL Content Block</blockName>
          <iconName></iconName>
          <odePagStructureOrder>1</odePagStructureOrder>

          <odePagStructureProperties>
            <odePagStructureProperty>
              <key>visibility</key>
              <value>true</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>teacherOnly</key>
              <value>false</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>allowToggle</key>
              <value>true</value>
            </odePagStructureProperty>
            <odePagStructureProperty>
              <key>minimized</key>
              <value>false</value>
            </odePagStructureProperty>
          </odePagStructureProperties>

          <odeComponents>

            <!-- ── iDevice: udl-content (Pattern 4 — htmlView-only) ──────────
                 jsonProperties is empty.  The entire iDevice state lives in
                 htmlView.  The importer reads htmlView and injects it directly
                 into the editor's content area; no JSON deserialisation occurs.
                 Note: the generator still writes the <jsonProperties></jsonProperties>
                 tag — it is never omitted, just left empty (OdeXmlGenerator.ts line 277).
                 ─────────────────────────────────────────────────────────────── -->
            <odeComponent>
              <odePageId>20251217062007PAGE03</odePageId>
              <odeBlockId>20251217062007BLK04</odeBlockId>
              <odeIdeviceId>20251217062007IDEV4</odeIdeviceId>
              <odeIdeviceTypeName>udl-content</odeIdeviceTypeName>

              <htmlView><![CDATA[<div class="exe-udl-content" id="exe-udl-20251217062007IDEV4">
  <div class="exe-udl-representation exe-udl-text" role="region" aria-label="Text representation">
    <h3>Read</h3>
    <p>Photosynthesis is the process by which plants convert sunlight into glucose.
       The overall equation is: 6CO<sub>2</sub> + 6H<sub>2</sub>O → C<sub>6</sub>H<sub>12</sub>O<sub>6</sub> + 6O<sub>2</sub>.</p>
  </div>
  <div class="exe-udl-representation exe-udl-visual" role="region" aria-label="Visual representation">
    <h3>Watch</h3>
    <p><a href="https://example.com/photosynthesis-diagram.png" target="_blank"
          rel="noopener noreferrer">View diagram</a></p>
  </div>
  <div class="exe-udl-representation exe-udl-action" role="region" aria-label="Action representation">
    <h3>Do</h3>
    <ol>
      <li>Label the parts of a chloroplast.</li>
      <li>Write the photosynthesis equation from memory.</li>
    </ol>
  </div>
</div>]]></htmlView>

              <jsonProperties></jsonProperties>
              <!-- Empty <jsonProperties> — Pattern 4.  The generator writes this empty
                   tag (not omitted) because its presence is part of the schema contract. -->

              <odeComponentsOrder>1</odeComponentsOrder>
              <odeComponentsProperties>
                <odeComponentsProperty>
                  <key>visibility</key>
                  <value>true</value>
                </odeComponentsProperty>
              </odeComponentsProperties>
            </odeComponent>

          </odeComponents>
        </odePagStructure>

      </odePagStructures>
    </odeNavStructure>

  </odeNavStructures>
</ode>
```

---

## Page tree summary

The three `<odeNavStructure>` elements above produce this navigation tree:

```
Overview  (PAGE01, order 1, no parent)
└── Topic A  (PAGE02, order 1, parent=PAGE01)
└── Topic B  (PAGE03, order 2, parent=PAGE01)
```

The importer rebuilds this tree by iterating all `<odeNavStructure>` elements and grouping
them by `<odeParentPageId>`. Order within a level is determined by `<odeNavStructureOrder>`.
Pages must appear in depth-first order in the XML (parent before its children) — the generator
in `OdeXmlGenerator.ts` guarantees this by construction.

---

## Validation

Validate the assembled XML the same way as the minimal example:

```bash
# From the directory containing both content.xml and content.dtd:
xmllint --noout --dtdvalid content.dtd content.xml && echo "valid"
```

Common validation errors in multi-page files:

- **Mismatched `<odePageId>` inside a block** — the `<odePageId>` inside each
  `<odePagStructure>` must equal the `<odePageId>` of the enclosing `<odeNavStructure>`.
- **Mismatched `<odeBlockId>` inside a component** — the `<odeBlockId>` inside each
  `<odeComponent>` must equal the `<odeBlockId>` of the enclosing `<odePagStructure>`.
- **Missing `<odeComponentsProperties>`** — this element must always be present; the
  generator writes `visibility=true` as a default when no explicit properties are set.
- **`]]>` inside a CDATA section** — if `<htmlView>` or `<jsonProperties>` content
  contains the sequence `]]>`, it must be split: `]]]]><![CDATA[>`. The generator handles
  this automatically via `escapeCdata()` in `OdeXmlGenerator.ts`.

---

## Next steps

- Validate the full element vocabulary in [../content-xml.md](../content-xml.md).
- See how this `content.xml` fits inside the ZIP archive in [full-package-tree.md](full-package-tree.md).
- Browse ready-to-use iDevice HTML/JSON snippets in [../idevices/snippets.md](../idevices/snippets.md).
- Understand how IDs are generated and scoped in [../ids.md](../ids.md).


# ===== doc/elpx-format/examples/full-package-tree.md =====

# Full package tree

This page annotates the complete `unzip -l` listing of the fixture file
`test/fixtures/really-simple-test-project.elpx`. That file is a real export produced by
the eXeLearning v4 codebase in this repository, so every entry name, size, and timestamp
is authoritative.

Use this listing as a quick orientation map. Each section below points to the subdoc that
covers the relevant files in depth.

Full container reference: [../container.md](../container.md).
Minimal content.xml walkthrough: [minimal-content-xml.md](minimal-content-xml.md).
Multi-page content.xml walkthrough: [multi-page-content-xml.md](multi-page-content-xml.md).

---

## Raw listing

```
Archive:  really-simple-test-project.elpx
  Length      Date    Time    Name
---------  ---------- -----   ----
    10696  04-27-2026 21:11   search_index.js

    13032  04-27-2026 21:11   content/css/base.css
     1996  04-27-2026 21:11   content/img/exe_powered_logo.png

    21476  04-27-2026 21:11   theme/screenshot.png
     4307  04-27-2026 21:11   theme/style.js
      490  04-27-2026 21:11   theme/config.xml
    12855  04-27-2026 21:11   theme/style.css
     1978  04-27-2026 21:11   theme/img/licenses.gif
     4813  04-27-2026 21:11   theme/img/icons.png

     -- 50 PNG icons under theme/icons/ (activity.png, ask.png, book.png, …) --
     1902  04-27-2026 21:11   theme/icons/info.png
     2133  04-27-2026 21:11   theme/icons/roadmap.png
      …
     2745  04-27-2026 21:11   theme/icons/english.png
     -- end of theme/icons/ --

    87533  04-27-2026 21:11   libs/jquery/jquery.min.js
    80743  04-27-2026 21:11   libs/bootstrap/bootstrap.bundle.min.js
   232018  04-27-2026 21:11   libs/bootstrap/bootstrap.min.css
   332347  04-27-2026 21:11   libs/bootstrap/bootstrap.bundle.min.js.map
   589698  04-27-2026 21:11   libs/bootstrap/bootstrap.min.css.map
    33609  04-27-2026 21:11   libs/exe_export.js
   115416  04-27-2026 21:11   libs/common.js
     2889  04-27-2026 21:11   libs/favicon.ico
     3107  04-27-2026 21:11   libs/common_i18n.js

     -- exe_atools (accessibility toolbar) — 14 files --
    23647  04-27-2026 21:11   libs/exe_atools/exe_atools.js
     6200  04-27-2026 21:11   libs/exe_atools/exe_atools.css
     2297  04-27-2026 21:11   libs/exe_atools/exe_atools.png
   144200  04-27-2026 21:11   libs/exe_atools/exe_atools_od_b.woff
   132640  04-27-2026 21:11   libs/exe_atools/exe_atools_od_bi.woff
   132408  04-27-2026 21:11   libs/exe_atools/exe_atools_od.woff
   130192  04-27-2026 21:11   libs/exe_atools/exe_atools_od_i.woff
    17184  04-27-2026 21:11   libs/exe_atools/exe_atools_ah.woff2
     9328  04-27-2026 21:11   libs/exe_atools/exe_atools_ah_ext.woff2
    14940  04-27-2026 21:11   libs/exe_atools/exe_atools_mo.woff2
    13508  04-27-2026 21:11   libs/exe_atools/exe_atools_mo_ext.woff2
     8636  04-27-2026 21:11   libs/exe_atools/exe_atools_mo_cy.woff2
     9584  04-27-2026 21:11   libs/exe_atools/exe_atools_mo_cy_ext.woff2
     5080  04-27-2026 21:11   libs/exe_atools/exe_atools_mo_vi.woff2
     -- end of exe_atools --

       52  04-27-2026 21:11   idevices/text/text.html
     1314  04-27-2026 21:11   idevices/text/exequextsq.svg
      342  04-27-2026 21:11   idevices/text/text.css
     8211  04-27-2026 21:11   idevices/text/text.js

     4955  04-27-2026 21:11   index.html
     5069  04-27-2026 21:11   html/page-1---1.html
     5110  04-27-2026 21:11   html/page-1---1--1.html
     5075  04-27-2026 21:11   html/page-1---2.html
     5040  04-27-2026 21:11   html/page-2.html
     5053  04-27-2026 21:11   html/page-2---1.html

    31098  04-27-2026 21:11   content.xml
     2251  04-27-2026 21:11   content.dtd
    67239  04-27-2026 21:11   screenshot.png
---------                     -------
  2444866                     95 files
```

The 50-icon and 14-font groups are collapsed for readability; the actual archive lists
each file individually. Run `unzip -l test/fixtures/really-simple-test-project.elpx`
in the repository root to see the full enumeration.

---

## Section walkthrough

### Root files

| File | Size | Description |
|------|------|-------------|
| `content.xml` | 31 KB | The ODE 2.0 project structure. The **only** file the importer requires — every other file is part of the rendered HTML payload. See [minimal-content-xml.md](minimal-content-xml.md) and the full reference in [../content-xml.md](../content-xml.md). |
| `content.dtd` | 2.2 KB | Bundled DTD for offline validation of `content.xml`. Generated from `ODE_DTD_CONTENT` in `src/shared/export/constants.ts:1006`. Always emitted by `ElpxExporter` in v4 packages. |
| `index.html` | 4.9 KB | First page rendered as a self-contained HTML5 document. It includes navigation, theme, and iDevice scripts via relative paths. This is what browsers open when the ZIP is extracted. |
| `screenshot.png` | 67 KB | 1280×720 PNG project thumbnail at the archive root. v4 packages always carry one; legacy packages without it are patched by [`scripts/add-screenshot.ts`](../../../scripts/add-screenshot.ts). See [../screenshot.md](../screenshot.md). |
| `search_index.js` | 11 KB | Pre-built search index for the runtime search box. Emitted only when `pp_addSearchBox` is `true` in `<odeProperties>`. |

This fixture has the search box enabled, hence the presence of `search_index.js`.
Distinct from `theme/screenshot.png`, which is the **theme** preview thumbnail used in the
theme picker — see the [`theme/`](#theme--active-theme-files) section.

---

### `html/` — per-page HTML files

```
html/page-1---1.html      5.1 KB   Page "Page 1 - 1"      (child of Page 1)
html/page-1---1--1.html   5.1 KB   Page "Page 1 - 1 - 1"  (child of Page 1-1)
html/page-1---2.html      5.1 KB   Page "Page 1 - 2"      (child of Page 1)
html/page-2.html          5.0 KB   Page "Page 2"           (root page)
html/page-2---1.html      5.1 KB   Page "Page 2 - 1"      (child of Page 2)
```

One `.html` file per page, except the first root page which becomes `index.html`.
Filenames are slugified from page titles; spaces become `-` and the slugifier escapes
literal hyphens by doubling them — that is why `Page 1 - 1` becomes `page-1---1.html`
(three dashes: the original `-` plus the two delimiter dashes around the spaces).
Internal links use relative paths (`../html/page-2.html`); `exe-node:<pageId>` URIs in
`content.xml` are resolved to these relative paths at export time.

The exporter that writes these files is `src/shared/export/exporters/Html5Exporter.ts`.
See [../container.md](../container.md) for the complete naming algorithm.

---

### `content/css/` — base stylesheet

```
content/css/base.css    13 KB   Core layout + utility classes for all themes
```

`base.css` defines the structural layout (`.exe-layout`, `.exe-block`, block visibility
toggles, accessibility toolbar) that is theme-independent. Themes layer their own
`theme/style.css` on top.

> **Note**: previous v3-era exports also wrote `content/css/icons/*.svg` (around 75 small
> SVG files for the runtime UI). The v4 exporter no longer ships them at this path —
> icon glyphs are inlined into `base.css` and `theme/style.css` as data URIs or referenced
> from the active theme's own `icons/` directory.

See [../themes.md](../themes.md) for the CSS layering model.

---

### `content/img/` — branding image

```
content/img/exe_powered_logo.png    2 KB    "Powered by eXeLearning" badge
```

Displayed in the footer when `pp_addExeLink` is `true` in `<odeProperties>`. The exporter
injects a `<footer>` element referencing this image into every page HTML file.

---

### `content/resources/` — project assets (absent in this fixture)

`content/resources/` is the directory that holds **project assets** — every image, audio
file, video, PDF, or other binary the user uploads through the file manager. The v4
layout is:

```
content/resources/<filename>                  # asset with no folderPath
content/resources/<folderPath>/<filename>     # asset inside a user-created folder
```

See [../assets.md](../assets.md) for the asset URL lifecycle and
[../container.md](../container.md) for the naming/dedup rules.

This particular fixture (`really-simple-test-project.elpx`) is **text-only** — it contains
six `text` iDevices but no uploaded media. Therefore `content/resources/` is **not present
at all** in the archive: empty directories are not emitted, and there are no asset files
to write. A non-empty fixture, e.g.
`test/fixtures/un-contenido-de-ejemplo-para-probar-estilos-y-catalogacion.elpx`, shows the
real layout. Inspect it with:

```bash
unzip -l test/fixtures/un-contenido-de-ejemplo-para-probar-estilos-y-catalogacion.elpx \
    | awk '/content\/resources\//'
```

> **What you will not see** in any v4 archive is the legacy v3 per-asset UUID subfolder
> pattern `content/resources/[0-9]{14}[A-Z0-9]{6}/<filename>` — it has been normalised
> away by [`scripts/flatten-elpx.ts`](../../../scripts/flatten-elpx.ts), which only
> collapses folders matching that exact regex (user folders are preserved). See
> [../validation.md](../validation.md).

---

### `theme/` — active theme files

```
theme/config.xml        490 B    Theme metadata (name, version, author)
theme/style.css          13 KB   Theme-specific CSS layered over base.css
theme/style.js          4.3 KB   Theme JavaScript (animations, special behaviours)
theme/screenshot.png     21 KB   Theme thumbnail shown in the theme picker
theme/img/icons.png     4.8 KB   Sprite sheet for decorative inline icons
theme/img/licenses.gif  2.0 KB   Creative Commons license badge variants
theme/icons/*.png        50 files  Pedagogical activity icons used in block headers
```

The theme directory is a copy of the active theme from
`public/files/perm/themes/base/<themeName>/`. For this fixture the active theme is `base`
(the default). `style.css` and `style.js` are loaded after Bootstrap and `base.css` in
every page `<head>`.

> Distinct from the **project-level** `screenshot.png` at the archive root: that is a
> thumbnail of the project's first page; this one is the theme's own preview image.

See [../themes.md](../themes.md) for the theme authoring guide and the full `config.xml`
schema.

---

### `theme/icons/` — pedagogical activity icons

50 PNG files named after pedagogical activity types (`activity.png`, `ask.png`, `book.png`,
`calculate.png`, …). Displayed in block headers when an educator assigns an activity type
to a block. Theme icon sets are part of the theme and can be replaced by a custom theme.

---

### `libs/` — runtime libraries

```
libs/jquery/jquery.min.js                88 KB   jQuery 3.x minified
libs/bootstrap/bootstrap.bundle.min.js   81 KB   Bootstrap 5 JS + Popper (minified)
libs/bootstrap/bootstrap.min.css        232 KB   Bootstrap CSS (minified)
libs/bootstrap/bootstrap.bundle.min.js.map  332 KB   JS source map (DevTools)
libs/bootstrap/bootstrap.min.css.map    590 KB   CSS source map (DevTools)
libs/common.js                          115 KB   Shared runtime utilities
libs/exe_export.js                       34 KB   Export-time helpers
libs/common_i18n.js                     3.1 KB   Localised strings (generated per export)
libs/favicon.ico                        2.9 KB   Browser tab icon
libs/exe_atools/                       14 files   Accessibility toolbar (JS, CSS, sprite, fonts)
```

`common.js` initialises page navigation, block collapse/expand, the search index, and
inter-page messaging. `common_i18n.js` is generated from the active locale at export time
(`Html5Exporter.generateI18nBundle()`), so its contents reflect the chosen `pp_lang`.
`exe_export.js` handles download, print, and share actions. The `exe_atools` directory
ships the runtime accessibility toolbar (font-size, contrast, dyslexia-friendly fonts —
WOFF/WOFF2 OpenDyslexic and high-contrast typefaces). Loaded only when
`pp_addAccessibilityToolbar` is `true`.

The base library set is the constant `BASE_LIBRARIES` in `src/shared/export/constants.ts:325`.
Conditional libraries (lightbox, MathJax, qTip, etc.) are added on demand via
`LIBRARY_PATTERNS` in the same file.

See [../libraries.md](../libraries.md) for the full library inventory.

---

### `idevices/text/` — text iDevice runtime files

```
idevices/text/text.html      52 B   Editor template stub (empty in export)
idevices/text/text.css      342 B   Styles for the text iDevice container
idevices/text/text.js       8.2 KB   Runtime behaviour for the text iDevice
idevices/text/exequextsq.svg 1.3 KB  Decorative quote-mark SVG used by the text iDevice
```

Every iDevice type that appears in the project ships a subdirectory under `idevices/`.
This fixture uses only the `text` iDevice, so only `idevices/text/` is present. If the
project also used a `quiz` iDevice there would also be an `idevices/quiz/` directory. The
files are copied from `public/files/perm/idevices/base/<type>/` at export time.

See [../idevices/snippets.md](../idevices/snippets.md) for iDevice HTML/JSON shape
documentation.

---

## Totals

| Section | Files | Approx. uncompressed size |
|---------|-------|---------------------------|
| Root (`content.xml`, `content.dtd`, `index.html`, `screenshot.png`, `search_index.js`) | 5 | 116 KB |
| `html/` | 5 | 25 KB |
| `content/css/` | 1 | 13 KB |
| `content/img/` | 1 | 2 KB |
| `theme/` (root files + `img/`) | 6 | 46 KB |
| `theme/icons/` | 50 | 110 KB |
| `libs/` (jQuery, Bootstrap, common.js, common_i18n.js, exe_export.js, favicon) | 9 | 1.45 MB |
| `libs/exe_atools/` | 14 | 650 KB |
| `idevices/text/` | 4 | 10 KB |
| **Total** | **95** | **~2.4 MB uncompressed** |

The bulk of the archive (over 80 %) is the runtime libraries (Bootstrap + exe_atools).
For a project that uses uploaded media, the `content/resources/` tree dominates instead.


# ===== doc/architecture.md =====

# eXeLearning Architecture

This document describes the technical architecture of eXeLearning, an educational content authoring tool built with modern web technologies.

## 1. Overview

### Design Philosophy

eXeLearning follows a **browser-first architecture** where:

- **Client is the source of truth**: The browser holds the authoritative state in IndexedDB and in-memory Yjs documents
- **Server is for synchronization**: The server acts as a stateless relay, coordinating between clients without storing document state
- **Explicit saves only**: Content is persisted to the server only when the user explicitly saves
- **Offline-capable**: Users can work without network connectivity; sync happens when online

### Key Principles

1. **Zero server memory overhead**: No Y.Doc stored on server per document
2. **P2P asset coordination**: Assets shared between collaborating clients via server coordination
3. **Content-addressable assets**: Same file content = same ID across all users
4. **Dependency injection**: All services use DI pattern for testability

### Runtime Modes (Server, Static, Embedded)

eXeLearning supports two primary runtime modes and one optional embedding mode:

| Mode | What runs | Persistence | Collaboration | Typical use |
|------|-----------|-------------|---------------|-------------|
| **Server (online)** | Bun + Elysia API + WebSocket | Server DB + client IndexedDB | Yes | Multi-user, hosted installs |
| **Static (offline)** | Pure static assets (no API) | Client IndexedDB + file save/export | No | Desktop installers, static hosting |
| **Embedded (iframe)** | Server or Static in iframe | Delegated to host via postMessage | Depends on mode | LMS, CMS, plugin embeds |

**Static mode** is built from the online app by removing database and API dependencies to stay stateless. The build bundles required catalog data (iDevices, themes, translations, parameters) into `dist/static` and runs fully in the browser. It is generated with:

```
make build-static
```

This is the same runtime used by the current offline (installable) eXeLearning desktop app. It improves simplicity and performance by avoiding any server persistence.

### Embedding Example (Static or Server)

When eXeLearning runs inside an iframe, it can coordinate file operations with the host page via `postMessage`. The app announces readiness with `EXELEARNING_READY` and can request open/save operations. A minimal host integration:

```html
<iframe
  id="exe"
  src="https://your-host/exelearning/"
  style="width: 100%; height: 100vh; border: 0;"
></iframe>

<script>
  const iframe = document.getElementById('exe');

  function postToExe(type, data = {}) {
    const requestId = `${Date.now()}-${Math.random().toString(16).slice(2)}`;
    iframe.contentWindow.postMessage({ type, requestId, ...data }, '*');
    return requestId;
  }

  window.addEventListener('message', async (event) => {
    const { type, requestId, bytes } = event.data || {};
    if (!type) return;

    if (type === 'EXELEARNING_READY') {
      // Optional: set trusted origins or request info
      postToExe('GET_PROJECT_INFO');
    }

    if (type === 'EXELEARNING_SAVE_REQUEST') {
      // Host handles file persistence
      // Example: upload bytes to your backend, then respond
      event.source.postMessage({ type: 'EXELEARNING_SAVE_RESPONSE', requestId, path: 'project.elpx' }, event.origin);
    }

    if (type === 'EXELEARNING_OPEN_REQUEST') {
      // Host provides bytes for a .elpx file (from disk or backend)
      const fileBytes = new Uint8Array(); // replace with real data
      event.source.postMessage({ type: 'EXELEARNING_OPEN_RESPONSE', requestId, bytes: fileBytes }, event.origin);
    }
  });
</script>
```

For production, restrict origins and validate all messages (see `EmbeddedFileSystem` and `EmbeddingBridge` for supported message types and security checks).

## 2. Technology Stack

| Component | Technology | Purpose |
|-----------|------------|---------|
| **Runtime** | [Bun](https://bun.sh/) | Fast JavaScript runtime and package manager |
| **Framework** | [Elysia](https://elysiajs.com/) | Type-safe web framework |
| **ORM** | [Kysely](https://kysely.dev/) | Type-safe SQL query builder |
| **Database** | SQLite / PostgreSQL / MySQL | Multi-database support |
| **Real-time** | WebSocket + [Yjs](https://yjs.dev/) | Collaborative editing |
| **Frontend** | Vanilla JavaScript | No framework dependencies |
| **Storage** | IndexedDB | Client-side asset and document storage |
| **Templates** | Nunjucks | Server-side HTML rendering |
| **Desktop** | Electron | Cross-platform desktop application |

## 3. System Architecture

```mermaid
graph TB
    subgraph "Browser (Client)"
        UI[User Interface]
        YDoc["Y.Doc (in-memory)"]
        IDB[(IndexedDB)]
        AM[AssetManager]
        WSH[WebSocket Handler]

        UI --> YDoc
        YDoc <--> IDB
        AM <--> IDB
        UI --> AM
        WSH --> YDoc
        WSH --> AM
    end

    subgraph "Server (Elysia + Bun)"
        Routes[REST Routes]
        WS[WebSocket Relay]
        RM[Room Manager]
        AC[Asset Coordinator]
        SM[Session Manager]
        Kysely[Kysely ORM]

        Routes --> SM
        Routes --> Kysely
        WS --> RM
        WS --> AC
        AC --> Kysely
    end

    subgraph "Storage"
        DB[(Database)]
        FS[File System]
    end

    Browser <-->|"REST API"| Routes
    Browser <-->|"WebSocket (Yjs Binary)"| WS
    Kysely --> DB
    SM --> FS
```

### Request Flow

1. **Page Load**: Browser fetches HTML from REST API, renders workarea
2. **Document Open**: YjsDocumentManager initializes Y.Doc, syncs from IndexedDB
3. **WebSocket Connect**: y-websocket provider connects for real-time sync
4. **Editing**: Changes update Y.Doc → replicated to peers via WebSocket
5. **Save**: User clicks save → REST API persists Yjs state to database

## 4. WebSocket & Yjs Collaboration

### 4.1 Stateless Relay Architecture

The WebSocket server does NOT maintain Y.Doc state:

```
┌─────────────────────────────────────────────────────────────┐
│                    Traditional Architecture                  │
│  Client A ──► Server Y.Doc ◄── Client B                     │
│              (memory overhead)                               │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                eXeLearning Stateless Relay                   │
│  Client A ──────► Relay ◄────── Client B                    │
│  (Y.Doc)     (zero memory)      (Y.Doc)                     │
└─────────────────────────────────────────────────────────────┘
```

**Benefits:**
- No memory per document on server
- Scales to many concurrent documents
- Client IndexedDB provides offline persistence

### 4.2 Connection Flow

```mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Room

    Client->>Server: WebSocket connect<br/>/yjs/project-{uuid}?token=JWT
    Server->>Server: Validate JWT token
    Server->>Server: Check project access
    Server->>Room: getOrCreateRoom()
    Room->>Room: Add connection
    Server->>Client: Connection established

    Client->>Server: Yjs sync step 1 (binary)
    Server->>Room: relayMessage() to other clients

    Note over Client,Server: Continuous sync during editing

    Client->>Server: Close connection
    Server->>Room: removeConnection()
    Room->>Room: Schedule cleanup (30s delay)
```

### 4.3 Message Protocol

The server distinguishes between two message types:

| Type | Detection | Handler |
|------|-----------|---------|
| **Yjs sync** | Binary, starts with bytes 0-2 | Relayed to room peers |
| **Asset protocol** | Binary with `0xFF` prefix + JSON | Handled by AssetCoordinator |

```typescript
// Message discrimination in message-parser.ts
if (message[0] === 0xFF) {
    // Asset protocol message
    const json = message.subarray(1);
    return { kind: 'asset', message: JSON.parse(json) };
}
// Default: Yjs binary message
return { kind: 'yjs', data: message };
```

### 4.4 Room Management

Rooms are created per document and track connected clients:

```typescript
interface Room {
    name: string;                    // "project-{uuid}"
    conns: Set<WebSocket>;           // Connected clients
    projectUuid: string;
    cleanupController?: AbortController;  // For cancellable cleanup
}
```

**Lifecycle:**
1. **Create**: First client connects → room created
2. **Active**: Messages relayed between clients
3. **Cleanup Scheduled**: Last client disconnects → 30s timer starts
4. **Cleanup Cancelled**: Client reconnects before timer → cancel cleanup
5. **Destroyed**: Timer fires → room deleted, assets cleaned up

### 4.5 Heartbeat & Keep-Alive

WebSocket connections use ping/pong for health checking:

| Environment | Ping Interval | Cleanup Delay |
|-------------|---------------|---------------|
| **Desktop** | 60s | 5s |
| **Server** | 30s | 30s |

The shorter server interval avoids proxy timeout issues (typically 60s).

## 5. Asset Management System

### 5.1 Browser-First Storage

Assets are stored primarily in IndexedDB on the client:

```javascript
// IndexedDB schema (exelearning-assets-v2)
{
    id: string,           // Content-addressable UUID
    projectId: string,    // Project reference
    blob: Blob,           // Actual file data
    mime: string,         // MIME type
    hash: string,         // SHA-256 hex
    size: number,
    uploaded: boolean,    // Server sync status
    filename: string
}
```

### 5.2 Content-Addressable URLs

Assets use deterministic IDs based on content hash:

```
asset://8f3e9c2a-1b4d-4f7e-9a3c-2d1e5f7a9b3c
asset://8f3e9c2a-1b4d-4f7e-9a3c-2d1e5f7a9b3c/photo.jpg
```

**Benefits:**
- Same file = same ID (deduplication)
- Idempotent uploads
- Efficient P2P sharing

### 5.3 P2P Asset Coordination

When multiple users collaborate, assets are shared via server coordination:

```mermaid
sequenceDiagram
    participant Alice as Alice (has asset)
    participant Server as Server
    participant Bob as Bob (needs asset)

    Alice->>Server: awareness-update<br/>["asset-1", "asset-2"]
    Note over Server: Track: Alice has asset-1, asset-2

    Bob->>Server: request-asset<br/>{assetId: "asset-1", priority: HIGH}
    Server->>Server: Check DB (not found)
    Server->>Server: Check peers (Alice has it)
    Server->>Alice: upload-request<br/>{assetId: "asset-1"}

    Alice->>Server: Upload asset-1 via REST
    Server->>Bob: asset-ready<br/>{assetId: "asset-1", url: "/api/..."}

    Bob->>Server: Download asset-1
    Bob->>Bob: Store in IndexedDB
```

### 5.4 Priority Queue System

Asset uploads are prioritized to ensure responsive UI:

| Priority | Value | Use Case |
|----------|-------|----------|
| CRITICAL | 100 | Asset needed for current render |
| HIGH | 75 | Asset on current page |
| MEDIUM | 50 | Asset on nearby pages |
| LOW | 25 | Background prefetch |
| IDLE | 0 | Normal save upload |

**Preemption rules:**
- Max 3 concurrent uploads per project
- Higher priority can preempt if: priority diff ≥ 50 AND upload running ≥ 2s

### 5.5 Save Flow

```mermaid
flowchart LR
    subgraph Browser
        A[User clicks Save] --> B[Get pending assets]
        B --> C[Create priority batches]
        C --> D[Upload batches in parallel]
        D --> E[Save Yjs state]
        E --> F[Mark assets uploaded]
    end

    subgraph Server
        D --> G[Store assets on disk]
        E --> H[Store Yjs snapshot in DB]
    end
```

**Batch configuration:**
- Critical: 1 asset per batch (fastest)
- High priority: max 5 files or 5MB per batch
- Normal: max 15 files or 10MB per batch
- Max concurrent batches: 5

## 6. Session Management

### 6.1 Session Lifecycle

Each opened project gets a unique session:

```typescript
interface ProjectSession {
    sessionId: string;        // UUID
    projectId: number;        // Database ID
    projectUuid: string;      // Project UUID
    sessionPath: string;      // tmp/{sessionId}/
    contentPath: string;      // Path to extracted content
    createdAt: Date;
    modifiedAt: Date;
}
```

Sessions are stored in-memory (`Map<sessionId, ProjectSession>`).

### 6.2 File System Structure

```
FILES_DIR/
├── tmp/{sessionId}/          # Temporary session directory
│   ├── content.xml           # Extracted ELP content
│   ├── assets/               # Uploaded assets
│   └── dist/                 # Export output
│
├── perm/odes/{projectId}/    # Permanent storage
│   └── assets/
│
└── data/
    └── chunks/{projectId}/   # Chunked upload temp storage
```

## 7. Export System

### 7.1 Supported Formats

| Format | Description | Use Case |
|--------|-------------|----------|
| **HTML5** | Self-contained website | Web hosting |
| **SCORM 1.2** | LMS package | Moodle, Blackboard (legacy) |
| **SCORM 2004** | LMS package | Modern LMS |
| **EPUB3** | E-book format | E-readers |
| **IMS CP** | Content package | Standards compliance |

### 7.2 Export Strategy Pattern

```typescript
interface ExportStrategy {
    export(session: ProjectSession, options: ExportOptions): Promise<string>;
    getManifest(): Promise<string>;
    copyAssets(): Promise<void>;
}

// Usage
const exporter = ExportFactory.create('scorm12');
const zipPath = await exporter.export(session, options);
```

## 8. Preview System (Service Worker Architecture)

The workarea preview uses a **Service Worker** to serve exported HTML files directly, ensuring the preview exactly matches the exported output.

### 8.1 Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                      WORKAREA                                │
├─────────────────────────────────────────────────────────────┤
│  Yjs Bridge                    PreviewPanelManager          │
│      │                               │                       │
│      │ onStructureChange()           │                       │
│      └──────────────────────────────►│                       │
│                                      │                       │
│                            1. Generate export                │
│                               (Html5Exporter)                │
│                                      │                       │
│                            2. Send to SW                     │
│                               (SET_CONTENT)                  │
│                                      │                       │
│                            3. Load iframe                    │
│                               /viewer/index.html             │
└─────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   SERVICE WORKER                             │
├─────────────────────────────────────────────────────────────┤
│  contentFiles: Map<path, ArrayBuffer>                        │
│                                                              │
│  fetch('/viewer/*') → handleViewerRequest()                  │
│      ├── Look up path in contentFiles                        │
│      ├── Return Response with correct MIME type              │
│      └── Inject external link handler for HTML               │
└─────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   PREVIEW IFRAME                             │
├─────────────────────────────────────────────────────────────┤
│  <iframe src="/viewer/index.html">                          │
│      │                                                       │
│      ├── CSS: /viewer/theme/style.css                       │
│      ├── JS:  /viewer/libs/common.js                        │
│      ├── IMG: /viewer/content/resources/image.jpg           │
│      └── All served by SW from memory!                       │
└─────────────────────────────────────────────────────────────┘
```

### 8.2 How It Works

1. **Generate Export**: When preview is requested, `Html5Exporter.generateForPreview()` generates all export files in memory as `Map<string, Uint8Array | string>`

2. **Send to Service Worker**: Files are sent to the SW via `postMessage({ type: 'SET_CONTENT', files })`

3. **Load Preview**: The iframe loads `/viewer/index.html` - all requests intercepted by SW

4. **Serve Files**: SW serves files from its in-memory cache with correct MIME types

### 8.3 Key Components

| Component | File | Purpose |
|-----------|------|---------|
| **Service Worker** | `public/app/preview-sw.js` | Intercepts `/viewer/*` requests |
| **Preview Panel** | `public/app/workarea/interface/elements/previewPanel.js` | UI and orchestration |
| **Export Generator** | `src/shared/export/exporters/Html5Exporter.ts` | Generates export files |
| **Browser API** | `src/shared/export/browser/index.ts` | Browser-side export functions |

### 8.4 Benefits

- **Exact match**: Preview IS the exported HTML (same code path, same output)
- **No workarounds**: No blob:// URL complexity for assets
- **Native PDF viewer**: PDFs work without PDF.js workaround (not in nested blob context)
- **External links**: Handled correctly (SW injects click handler)
- **Multi-page navigation**: Works exactly like the real export

### 8.5 Service Worker Protocol

```javascript
// Messages sent to Service Worker
{ type: 'SET_CONTENT', files: Map<path, ArrayBuffer> }  // Set preview content
{ type: 'CLEAR_CONTENT' }                                // Clear preview cache
{ type: 'CLAIM_CLIENTS' }                                // Activate SW for page
```

## 9. Database Architecture

### 9.1 Multi-Database Support

Kysely ORM with dialect adapters:

```typescript
// src/db/dialect.ts
function createDialect(): Dialect {
    switch (process.env.DB_DRIVER) {
        case 'pdo_sqlite':
            return new BunWorkerDialect({ /* SQLite config */ });
        case 'pdo_pgsql':
            return new PostgresDialect({ /* PostgreSQL config */ });
        case 'pdo_mysql':
            return new MysqlDialect({ /* MySQL config */ });
    }
}
```

### 9.2 Query Pattern with Dependency Injection

All queries accept `db` as first parameter for testability:

```typescript
// src/db/queries/projects.ts
export async function findProjectByUuid(
    db: Kysely<Database>,
    uuid: string
): Promise<Project | undefined> {
    return db.selectFrom('projects')
        .where('uuid', '=', uuid)
        .selectAll()
        .executeTakeFirst();
}
```

**Testing with DI:**
```typescript
// In tests
configure({
    queries: { findProjectByUuid: mockFindProjectByUuid }
});

afterEach(() => resetDependencies());
```

## 10. Configuration

### 10.1 Environment Variables

Key configuration in `.env`:

```bash
# Server
APP_PORT=8080
APP_SECRET=your-jwt-secret

# Database
DB_DRIVER=pdo_sqlite          # pdo_sqlite | pdo_pgsql | pdo_mysql
DB_PATH=/mnt/data/exelearning.db

# File Storage
FILES_DIR=/mnt/data/

# Optional
BASE_PATH=/exelearning        # URL prefix for subdirectory install
APP_AUTH_METHODS=password     # password,cas,openid,guest
```

### 10.2 Desktop vs Server Configuration

| Setting | Desktop (Electron) | Server |
|---------|-------------------|--------|
| Ping interval | 60s | 30s |
| Cleanup delay | 5s | 30s |
| Compact threshold | 100 updates | 50 updates |
| WebSocket timeout | 70s | 40s |

## 11. Key File Locations

### Backend (src/)

| Path | Purpose |
|------|---------|
| `src/index.ts` | Elysia entry point |
| `src/routes/` | REST API routes |
| `src/services/` | Business logic |
| `src/db/client.ts` | Kysely instance |
| `src/db/queries/` | Database queries |
| `src/websocket/yjs-websocket.ts` | WebSocket handler |
| `src/websocket/room-manager.ts` | Room lifecycle |
| `src/websocket/asset-coordinator.ts` | P2P coordination |
| `src/shared/export/exporters/Html5Exporter.ts` | HTML5 export (also used for preview) |
| `src/shared/export/browser/index.ts` | Browser-side export API |

### Frontend (public/app/)

| Path | Purpose |
|------|---------|
| `public/app/yjs/YjsDocumentManager.js` | Y.Doc management |
| `public/app/yjs/AssetManager.js` | IndexedDB storage |
| `public/app/yjs/AssetWebSocketHandler.js` | Asset protocol |
| `public/app/yjs/SaveManager.js` | Save orchestration |
| `public/app/yjs/YjsProjectBridge.js` | Coordination hub |
| `public/app/preview-sw.js` | Preview Service Worker |
| `public/app/workarea/interface/elements/previewPanel.js` | Preview panel UI |

### Configuration

| Path | Purpose |
|------|---------|
| `.env` | Environment configuration |
| `tsconfig.json` | TypeScript config |
| `bunfig.toml` | Bun configuration |
| `Makefile` | Build commands |

## 12. Testing

### Test Strategy

- **Unit tests**: Next to source files (`*.spec.ts`)
- **Integration tests**: `test/integration/`
- **E2E tests**: Playwright
- **Coverage target**: 90%

### Running Tests

```bash
# Run all unit tests
make test-unit

# Run with coverage
make test-coverage

# Run specific test
DB_PATH=:memory: ELYSIA_FILES_DIR=/tmp/test bun test src/path/to/file.spec.ts
```

### DI Pattern for Testing

Never use `mock.module()`. Use dependency injection:

```typescript
// Configure mocks
configure({
    db: testDb,
    queries: { findById: mockFindById }
});

// Reset after test
afterEach(() => resetDependencies());
```

## 13. Security

### Authentication

- JWT tokens for API and WebSocket authentication
- Token passed in query string for WebSocket (`?token=JWT`)
- Multiple auth methods: password, CAS, OpenID Connect, guest

### Authorization

- Project access checked before WebSocket connection
- User ID tracked per connection for audit
- Path traversal prevention with `isPathSafe()`

### WebSocket Security

```typescript
// Connection validation
ws.on('open', async () => {
    const token = url.searchParams.get('token');
    const decoded = await verifyToken(token);
    if (!decoded) {
        ws.close(4001, 'Invalid token');
        return;
    }
    const hasAccess = await checkProjectAccess(db, decoded.userId, projectUuid);
    if (!hasAccess) {
        ws.close(4003, 'Access denied');
        return;
    }
});
```

## 14. Theme Architecture

### 14.1 Theme Types

eXeLearning supports three types of themes:

| Type | Source | Storage | Served By |
|------|--------|---------|-----------|
| **Base** | Built-in with eXeLearning | Server `/perm/themes/base/` | Server |
| **Site** | Admin-installed for all users | Server `/perm/themes/site/` | Server |
| **User** | Imported by user or from .elpx | Client IndexedDB + Yjs | **Never server** |

### 14.2 Server Themes (Base & Site)

**Base themes** are included with eXeLearning and synchronized at startup:
- Located in `/public/files/perm/themes/base/`
- Cannot be modified by users
- Served directly by the server

**Site themes** are installed by administrators for all users:
- Located in `/perm/themes/site/`
- Admin can activate/deactivate themes
- Admin can set a default theme for new projects
- Served directly by the server

### 14.3 User Themes (Client-Side Only)

> **Important**: User themes are NEVER stored or served by the server.

User themes are stored entirely on the client side:

```
┌─────────────────────────────────────────────────────────────────────┐
│                     USER THEME STORAGE                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  IndexedDB (per-user isolation)                                     │
│  └── user-themes store: key = "userId:themeName"                    │
│      └── Each user's themes isolated by userId prefix               │
│      └── User "alice" cannot see user "bob"'s themes                │
│                                                                     │
│  Yjs themeFiles (project document)                                  │
│  └── Currently selected user theme (for collaboration/export)       │
│                                                                     │
│  .elpx export                                                       │
│  └── Embedded theme files (for portability)                         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 14.4 User Theme Flow

```
1. IMPORT THEME
   User uploads ZIP → Stored in IndexedDB (local storage)

2. SELECT THEME
   User selects theme → Copied to Yjs themeFiles
   (enables collaboration and export)

3. CHANGE TO ANOTHER THEME
   User selects different theme → Removed from Yjs
   (but remains in IndexedDB for future use)

4. EXPORT PROJECT (.elpx)
   If user theme selected → Embedded in ZIP

5. OPEN PROJECT WITH EMBEDDED THEME
   Another user opens .elpx → Theme extracted to their IndexedDB
   (if ONLINE_THEMES_INSTALL is enabled)
```

### 14.5 Admin Configuration

```bash
# Allow users to import/install styles
ONLINE_THEMES_INSTALL=1    # 1 = enabled (default), 0 = disabled
```

When disabled (`ONLINE_THEMES_INSTALL=0`):
- Users cannot import external themes via the interface
- Users cannot load custom embbeded themes in .elpx files

### 14.6 Why User Themes Are Client-Side

This design follows the same pattern as other user-specific data (like favorite iDevices):

1. **Per-user storage**: Each user's themes are private to them
2. **No server storage**: Themes don't consume server disk space
3. **Collaboration via Yjs**: Selected theme is shared with collaborators in real-time
4. **Portability**: Themes embedded in .elpx can be opened anywhere
5. **Offline capability**: Themes work without server connectivity

---

## Further Reading

- [Real-Time Collaboration](development/real-time.md) - WebSocket and Yjs details
- [REST API](development/rest-api.md) - API endpoints
- [Testing](development/testing.md) - Test patterns and coverage
- [Creating Styles](development/styles.md) - How to create custom themes


# ===== doc/conventions.md =====

# Project Conventions

This document describes stable conventions and behaviors in the eXeLearning codebase that are intentional and should not be changed without careful consideration and updating this documentation.

---

## Legacy .elp (v2.x) Import – Root Node Flattening

### Background

Legacy `contentv3.xml` files from eXeLearning 2.x have a structural pattern where:

- A **single root node** acts as a container for the entire document
- All meaningful content pages are **children of that root node**
- The root node has a title and metadata, but conceptually behaves like a wrapper

This structure does **not** match the target content model of the new version, where multiple top-level pages are expected.

### Transformation Rule

When importing a legacy `contentv3.xml` with a single root node that has children:

1. **The legacy root node is imported as the first page** (level 0, no parent)
2. **All direct children of the root are promoted to top-level pages** (level 0, no parent)
3. **Deeper descendants keep their parent relationships** but have their levels recalculated

### Before/After Example

**Legacy Structure (contentv3.xml):**

```
Root
 ├─ Child A
 │   └─ Grandchild A1
 ├─ Child B
 └─ Child C
```

**Imported Structure:**

```
Page 1: Root         (level 0, parent: null)
Page 2: Child A      (level 0, parent: null)      ← promoted
Page 3: Grandchild A1 (level 1, parent: Child A)   ← preserved
Page 4: Child B      (level 0, parent: null)      ← promoted
Page 5: Child C      (level 0, parent: null)      ← promoted
```

### Key Points

| Aspect | Behavior |
|--------|----------|
| Root node | Becomes first top-level page |
| Root's direct children | Promoted to top-level (no parent) |
| Grandchildren | Keep parent relationship, level recalculated |
| Deeper nesting | Relationships preserved, levels adjusted |
| Content & metadata | Fully preserved |
| iDevices | Fully preserved |

### When Flattening Applies

Flattening is applied **only** when:

1. The document has **exactly one root node** (a node with no parent)
2. That root node has **at least one direct child**

Flattening is **not** applied when:

- There are multiple root nodes (structure is already flat)
- The single root has no children (nothing to flatten)

### Implementation Details

The flattening logic is implemented in:

- **File:** `src/services/xml/legacy-xml-parser.ts`
- **Functions:** `shouldFlattenRootChildren()`, `flattenRootChildren()`
- **Integration point:** `buildPageHierarchy()`

### Rationale

This transformation ensures that:

1. Legacy documents import into a **clean, predictable top-level structure**
2. The content model aligns with the new version's expectations
3. Users don't need to manually reorganize imported content

### Important Notes

- This behavior is **intentional and by design** – it is not a bug
- This transformation applies **only to legacy v2.x imports** (`contentv3.xml`)
- Do not change this behavior without updating:
  - The code comments in `legacy-xml-parser.ts`
  - This documentation
  - The test suite

---

## Legacy .elp (v2.x) Import – iDevice Box Splitting

### Background

Legacy `contentv3.xml` files from eXeLearning 2.x have a layout limitation:

- Pages can contain **multiple iDevices**
- Each iDevice has its **own title**
- The legacy format does **not** explicitly define layout boxes (blocks)

Without special handling, the import process would:

- Create **one single box per page**
- Place **all iDevices inside that box**
- Cause **loss of individual iDevice titles**

### Transformation Rule

When importing a legacy `contentv3.xml`:

1. **Each iDevice is placed in its own box** (block)
2. **The iDevice's title becomes the box title**
3. **No iDevices are grouped together** in a single box
4. **Order of iDevices is preserved**

### Before/After Example

**Legacy Page (contentv3.xml):**

```
Page
 └─ idevices list
     ├─ iDevice: Introduction (title: "Introduction")
     ├─ iDevice: Objectives (title: "Objectives")
     └─ iDevice: Activity (title: "Activity")
```

**Imported Structure:**

```
Page
 ├─ Box: "Introduction"
 │   └─ iDevice
 ├─ Box: "Objectives"
 │   └─ iDevice
 └─ Box: "Activity"
     └─ iDevice
```

### Key Points

| Aspect | Behavior |
|--------|----------|
| iDevices per box | Exactly one |
| Box title | Taken from iDevice title |
| iDevice order | Preserved |
| Missing titles | Default to empty string |

### When Box Splitting Applies

Box splitting is applied **only** when:

- Opening or importing **legacy `.elp` files (v2.x / contentv3.xml)**
- Files use the Python pickle-based format

### When Box Splitting Does NOT Apply

Box splitting is **not** applied to:

- **Modern `.elpx` files** – existing box structure is preserved as-is
- **New projects** – no legacy conversion needed
- **Content already using modern layout** – boxes and iDevices remain unchanged

### Implementation Details

The box splitting logic is implemented in:

**Backend:**
- **File:** `src/services/xml/legacy-xml-parser.ts`
- **Functions:** `extractIdeviceTitle()`, `extractComponents()`, `convertPagesToRealOdeNavStructures()`

**Frontend:**
- **File:** `public/app/yjs/LegacyXmlParser.js`
- **Functions:** `extractIdeviceTitle()`, `extractNodeBlocks()`, `extractIDevicesWithTitles()`

### Rationale

This transformation ensures that:

1. **iDevice titles are never lost** during import
2. Imported content matches the **mental model of modern layouts**
3. Users don't need to **manually split boxes** after import
4. Each content block has a **meaningful, descriptive title**

### Important Notes

- This behavior is **intentional and by design** – it is not a bug
- This transformation applies **only to legacy v2.x imports** (`contentv3.xml`)
- **Modern `.elpx` files are NOT affected** – their box structure is preserved
- Do not change this behavior without updating:
  - The code comments in both backend and frontend parsers
  - This documentation
  - The test suite

---

## Legacy .elp (v2.x) Import – Editable iDevice Conversion

### Background

Legacy `contentv3.xml` files from eXeLearning 2.x contain iDevices that were implemented as **specialized variants of a Text iDevice**, distinguished mainly by:

- An **icon** (e.g., lightbulb for Reflection, document for Activity)
- A **semantic label** (e.g., "Prior Knowledge", "Objectives", "Reflection")

Examples of such legacy iDevice types include:

- Activity
- Reading Activity
- Prior Knowledge
- Objectives
- Reflection
- FreeText, GenericIdevice
- Spanish FPD variants (Tareas, Comillas, NotaInformacion, etc.)

### The Editability Problem

These legacy iDevices:

- Were technically **Text-based** containers
- Relied on the **legacy editor logic**
- Have **no direct editable equivalent** in modern eXeLearning

If imported verbatim without conversion:

| Issue | Symptom |
|-------|---------|
| Edit button disabled | `btn-edit-idevice disabled` class present |
| Undefined identifier | `identifier="undefined"` in DOM |
| Content locked | Double-click opens editor but content cannot be modified |
| User frustration | iDevice is effectively **read-only** |

### Historical Precedent (Symfony Legacy)

In the **Symfony legacy implementation**, a specific workaround existed:

- When opening a legacy `.elp` in eXe 3:
  - These specialized legacy iDevices were **converted into a standard Text iDevice**
  - The content was preserved
  - The result was fully editable

This behavior is **recovered and preserved** in the current implementation.

### Transformation Rule

When opening or importing a legacy `.elp` (`contentv3.xml`):

1. **Detect legacy text-based iDevices** that have no modern editable counterpart
2. **Automatically convert them to modern Text iDevice** (`type: 'text'`)
3. **Preserve the original content** (HTML)
4. **Preserve the original title** (if present)
5. Ensure the resulting iDevice:
   - Has a **valid identifier**
   - Has the **Edit button enabled**
   - Is **fully editable** in modern eXeLearning

### iDevice Conversion Table

**Text-based iDevices (convert to `text`):**

| Legacy iDevice Type | Description | Conversion |
|---------------------|-------------|------------|
| FreeTextIdevice | Free text content | → text |
| FreeTextfpdIdevice | FPD variant | → text |
| GenericIdevice | Generic iDevice | → text |
| ReflectionIdevice | Reflection activity | → text |
| ReflectionfpdIdevice | FPD variant | → text |
| ReflectionfpdmodifIdevice | Modified FPD variant | → text |
| TareasIdevice | Tasks (Spanish) | → text |
| ListaApartadosIdevice | List sections (Spanish) | → text |
| ComillasIdevice | Quotes (Spanish) | → text |
| NotaInformacionIdevice | Note/Information | → text |
| NotaIdevice | Note | → text |
| CasopracticofpdIdevice | Case study FPD | → text |
| CitasparapensarfpdIdevice | Quotes to think | → text |
| DebesconocerfpdIdevice | Must know | → text |
| DestacadofpdIdevice | Highlighted | → text |
| OrientacionestutoriafpdIdevice | Teacher guidelines | → text |
| OrientacionesalumnadofpdIdevice | Student guidelines | → text |
| ParasabermasfpdIdevice | To learn more | → text |
| RecomendacionfpdIdevice | Recommendation | → text |
| EjercicioresueltofpdIdevice | Solved exercises | → text |
| WikipediaIdevice | Wikipedia embed | → text |
| RssIdevice | RSS feed | → text |
| AppletIdevice | Java applet (obsolete) | → text |

**Interactive iDevices (mapped to modern equivalents):**

| Legacy iDevice Type | Modern Type |
|---------------------|-------------|
| TrueFalseIdevice | trueorfalse |
| VerdaderofalsofpdIdevice | trueorfalse |
| MultichoiceIdevice | quick-questions-multiple-choice |
| EleccionmultiplefpdIdevice | quick-questions-multiple-choice |
| MultiSelectIdevice | quick-questions-multiple-choice |
| SeleccionmultiplefpdIdevice | quick-questions-multiple-choice |
| ClozeIdevice | complete |
| ClozefpdIdevice | complete |
| ClozelangfpdIdevice | complete |
| ImageMagnifierIdevice | magnifier |
| GalleryIdevice | image-gallery |
| CasestudyIdevice | casestudy |
| FileAttachIdevice, AttachmentIdevice | text (for editability) |
| ExternalUrlIdevice | external-website |
| QuizTestIdevice | quick-questions |

**Modern iDevices:**

| iDevice Type | Handling |
|--------------|----------|
| JsIdevice | Preserved (modern JSON-based iDevice system) |

**Fallback:**

Any unrecognized legacy iDevice type is **converted to `text`** to ensure editability.

### When This Applies

This conversion is applied **only** when:

- Opening or importing **legacy `.elp` files (v2.x / contentv3.xml)**
- Files use the Python pickle-based format

### When This Does NOT Apply

Conversion is **not** applied to:

- **Modern `.elpx` files** – iDevice types are preserved as defined
- **New projects** – no legacy conversion needed
- **Native EXENEW iDevices** – already use modern type system

### Implementation Details

The conversion logic is implemented in **both** backend and frontend:

**Backend:**
- **File:** `src/services/xml/legacy-xml-parser.ts`
- **Function:** `mapIdeviceType()`

**Frontend:**
- **File:** `public/app/yjs/LegacyXmlParser.js`
- **Function:** `mapIdeviceType()`

Both implementations must be kept in sync. When adding new iDevice type mappings, update both files.

### Rationale

**"Editable content takes precedence over preserving obsolete iDevice types."**

This transformation ensures that:

1. **No legacy content becomes read-only** – users can always edit their content
2. **Content is preserved exactly** – only the iDevice type metadata changes
3. **User experience is consistent** – all iDevices behave the same way
4. **Legacy compatibility is maintained** – matches historical eXe 3 behavior

### Important Notes

- This behavior is **intentional and by design** – it is not a bug
- This transformation applies **only to legacy v2.x imports** (`contentv3.xml`)
- **Modern `.elpx` files are NOT affected** – their iDevice types are preserved
- Do not change this behavior without updating:
  - The code comments in `legacy-xml-parser.ts` (backend)
  - The code comments in `LegacyXmlParser.js` (frontend)
  - This documentation
  - The test suite

---

## Legacy .elp (v2.x) Import – iDevice Icon Mapping

### Background

Legacy `contentv3.xml` files from eXeLearning 2.x store **icon names** directly in the iDevice dictionary:

```xml
<string role="key" value="icon"/>
<unicode value="preknowledge"/>
```

These icon names correspond to theme icon files (e.g., `think.png`, `objectives.png`).

### The Icon Problem

Some legacy icon names do **not** directly match modern theme icon filenames:

| Legacy Icon Name | Theme Icon File |
|------------------|-----------------|
| `preknowledge` | `think.png` |
| `reading` | `book.png` |
| `casestudy` | `case.png` |

Without mapping, these icons would not display correctly in the imported content.

### Transformation Rule

When importing a legacy `contentv3.xml`:

1. **Extract the icon name** from the iDevice dictionary (`icon` field)
2. **Map legacy icon names** to modern theme icon names (if different)
3. **Assign the icon to the block** (not the iDevice)
4. **Icons that match directly** (e.g., `objectives`, `reflection`) pass through unchanged

### Icon Mapping Table

| Legacy Icon Name | Theme Icon Name | Theme File |
|------------------|-----------------|------------|
| `preknowledge` | `think` | `think.png` |
| `reading` | `book` | `book.png` |
| `casestudy` | `case` | `case.png` |
| `objectives` | `objectives` | `objectives.png` (no change) |
| `reflection` | `reflection` | `reflection.png` (no change) |
| `activity` | `activity` | `activity.png` (no change) |
| `video` | `video` | `video.png` (no change) |
| `info` | `info` | `info.png` (no change) |
| `technology` | `technology` | `technology.png` (no change) |
| `file` | `file` | `file.png` (no change) |
| `pieces` | `pieces` | `pieces.png` (no change) |
| `draw` | `draw` | `draw.png` (no change) |
| `competencies` | `competencies` | `competencies.png` (no change) |

### Theme Icon Availability

Icons are loaded from the theme's `icons/` directory. Available icons in the base theme include:

- `activity`, `agreement`, `alert`, `arts`, `ask`, `book`, `calculate`, `case`
- `chrono`, `collaborative`, `competencies`, `diary`, `diary_alt`, `discuss`
- `download`, `draw`, `english`, `experiment`, `explore`, `file`, `gallery`
- `geography`, `guide`, `history`, `info`, `interactive`, `letters`, `listen`
- `math`, `music`, `nature`, `objectives`, `observe`, `passport`, `perform`
- `piece`, `pieces`, `play`, `present`, `reflection`, `roadmap`, `share`
- `sport`, `start`, `stop`, `suitcase`, `technology`, `think`, `think_alt`, `video`

### Key Points

| Aspect | Behavior |
|--------|----------|
| Icon source | iDevice's `icon` field in dictionary |
| Icon destination | Block's `iconName` property |
| Missing icons | Empty string (no icon displayed) |
| Unknown icons | Passed through as-is (may not display if not in theme) |

### When Icon Mapping Applies

Icon mapping is applied **only** when:

- Opening or importing **legacy `.elp` files (v2.x / contentv3.xml)**
- The iDevice has an `icon` field in its dictionary

### Implementation Details

The icon mapping logic is implemented in:

- **File:** `public/app/yjs/LegacyXmlParser.js`
- **Static property:** `LegacyXmlParser.LEGACY_ICON_MAP`
- **Functions:** `extractIDevicesWithTitles()`, `extractNodeBlocks()`

The icon is stored on the block (not the iDevice) because in the modern system, icons are a block-level property.

### Rationale

This transformation ensures that:

1. **Visual appearance is preserved** from legacy content
2. **Theme icons display correctly** without user intervention
3. **Semantic meaning** of iDevices (Objectives, Reflection, etc.) is visible via icons
4. **User experience is consistent** with the original content

### Important Notes

- This behavior is **intentional and by design** – it is not a bug
- This transformation applies **only to legacy v2.x imports** (`contentv3.xml`)
- **Modern `.elpx` files are NOT affected** – their icons are preserved as-is
- Do not change this behavior without updating:
  - The `LEGACY_ICON_MAP` in `LegacyXmlParser.js`
  - This documentation
  - The test suite

---

## Adding New Conventions

When adding new conventions to this document:

1. Provide clear background context
2. Include before/after examples where applicable
3. Document when the convention applies and when it doesn't
4. Reference the implementation files
5. Explain the rationale
6. Update related code comments to reference this document