# Elabora course format — specification 0.2 **Status:** draft for implementation, 6 October 2026. **Format id:** `elabora/0.1`. **Licence of this text:** Apache-2.0. The JSON Schemas in [`packages/format/schemas/0.1.10/`](packages/format/schemas/0.1.10/) are normative; this document explains them. Where they disagree, the schemas win. The format describes an e-learning module as plain files that people, agents and other tools can read and write. It separates three layers with different rules: | Layer | Files | Who changes it | Guarantee | |---|---|---|---| | **Contract** (the plan and its versions) | `plan.json`, `plan-versions/` | The author and their agent write the plan; a person makes its versions and records the client's validation of one | A version never changes (its content hash); release builds need a validated version and list what changed since | | **Blocks** | `course.json`, `screens/*.json` | Authors and agents, freely | Every value is checked against a schema (built-in or component) | | **Components** (templates) | `components//` | Agents and developers; authors edit instances | Templates without code, behaviour hooks, fallback to native blocks, versioned with migrations | | **Free objects** (governed code) | `objects//` | Agents, on explicit request; authors edit declared props only | Manifest + tests + sandbox, replayed at every change | ## 1. Project layout ``` course.json course settings, sections and screen order, variables, theme, tracking plan.json the plan, as it is now: objectives, ordered items, validated texts, questions, sources screens/.json one file per screen objects// free objects: object.manifest.json, object.js, object.tests.json, object.notes.md, object.gates.json (last gate run) components// course components (block types and screen layouts): component.json, template.html, component.css, migrations.mjs theme/ course stylesheet and embedded fonts (course.json theme) generators/ asset generators (*.mjs) and provenance.json of the assets they produced assets/ media files referenced by blocks (portable ASCII names); the audio of narration lines in assets/narration/// (§4.7) plan-versions/V.json the plan's versions (V1, V2…): frozen copies, their sends and the client's validation plan-versions/notes.json the author's notes for the client on changes in no version yet translations/.xlf translations of the course (XLIFF 2.0) and .approval.json, approval of the translated plan elabora.lock.json permanent short keys of stateful elements and component versions (generated; keep under version control) AGENTS.md rules for agents working on this course sources/ the author's files the course is made from, and their readable versions (.md, .files/): not part of the course ``` Tools keep their own data beside these files, in `.elabora/` by default: the journal of changes, the backup versions, the agents' activity and the transcripts of Elabora's chat ([storage](docs/architecture/storage.md#machine-local-data)). It is machine-local, never part of the course: in Elabora's chat, everything the agent writes during one turn is one batch of the journal, undone at once, and the tools refused to it (a file edit, a shell) are kept with their target, never any content. `sources/` is reserved: what it holds is never validated, built or published, and a course file that points into it is an error (`E_SOURCE_REFERENCED`). Tools may keep a readable version of each source beside it (`.md`, whose first line is an `` marker, and `.files/`). All JSON files are UTF-8, and may carry `"$schema"` pointing to `https://elabora.studio/schemas/0.1.10/.schema.json`. Tools write them with two-space indentation and a final newline. ## 2. Identifiers | Kind | Pattern | Example | Scope | |---|---|---|---| | Course elements (sections, screens, layers, blocks, events, objects) | `^[a-z][a-z0-9-]{0,47}$` | `evaluation-q1` | Unique in the whole course | | Plan elements (objectives, items, texts, questions, sources) | `^[A-Z][A-Z0-9_-]{0,31}$` | `OBJ-2`, `ITEM-5`, `Q-12` | Unique in the plan | | Variables | `^[a-z][a-zA-Z0-9_]{0,31}$` | `bonsReflexes` | Unique in the course | | Options (quiz, decision) | `^[a-z0-9]{1,8}$` | `a`, `b` | Unique in their block | | Dialogue nodes, endings and their variables | `^[a-z][a-z0-9-]{0,47}$` (variables: as course variables) | `premiere-question` | Unique in their dialogue; a dialogue's options are unique in their node | | Narration and dialogue lines | `^[a-z][a-z0-9-]{0,47}$` | `l2`, `m1` | Unique in their screen, across its narration, its layers and its dialogues | Ids are permanent: learner progress is keyed by id (§9), and tools never give an element another id on their own. Renaming is one explicit command, `elabora rename ` (MCP `elabora_rename`), for sections, screens, layers, blocks and events: every reference follows (sections, events, translation unit ids, stylesheet selectors on `data-section`, `data-screen`, `data-layer` and `data-block`), a screen file takes the new name, and `elabora.lock.json` keeps the element's key under its new id. Waivers of the plan that name the id follow it. It is refused for an id already in use or one that does not match the pattern. An id is never reused for something else. ## 3. Contract layer: `plan.json` and its versions The plan is the storyboard the client validates. `plan.json` is always the plan as it is now (the working copy); its versions are frozen copies of it in `plan-versions/` (D52). It holds: - `objectives[]`: observable statements (`statement`), a `short` name, Bloom level, success criterion, sources; - `items[]`: the ordered storyboard. Each item has a `kind` (`intro`, `exposition`, `demonstration`, `practice`, `scenario`, `assessment`, `summary`), a `part`, the objectives it serves, optional `lockedTexts[]` (validated texts, `verbatim: true` for one the client wants « à l'identique »), `questions[]` (validated assessment items with options, correctness and feedback) and `voiceover[]` (the item's voice-over, line by line: `speaker`, `text`; translated with the plan, not kept word for word in the module; written by `elabora plan voiceover`; a screen covering the item takes it as its narration script, `elabora narration from-plan`); - `sources[]`, `businessGoal`, `audience`, `duration` (the learner time asked for, in minutes: `min`, `max`), `spacing[]` (retrieval planned after the module), `waivers[]` (approved exceptions to pedagogical warnings). - before its validation (D51): `decided[]`, what the agent decided by itself because the author left it open (`topic`, `choice`, `why`, `items`), and `question`, the one question it asks the author now (`text`, `topic`, `items`). Validating a version removes both, and no version holds them: they are never part of the contract. Validated questions are choice questions (`mode` `single` or `multiple`, with `options`) or numeric questions (`mode: "numeric"`, with `answer`, `tolerance`, `unit`, `feedback` and `misconceptions`), reused by quiz and numeric blocks respectively. **Writing the plan.** The author and their agent write `plan.json` at any time, before and after a validation: `elabora plan write --from | --patch ` (MCP `elabora_write_plan`) checks it against its schema first, and the screens of items moved follow them (D50). A validated text is reworded in the plan (`elabora plan text`), and every block that shows it by `textRef` follows. An agent's write that changes a text kept `verbatim` (its words, its flag, or the text removed) is refused (`E_PLAN_VERBATIM_LOCKED`): only the author changes it. **Versions.** `plan-versions/V.json` (schema `plan-version`) holds `version` (its number, the file's name), `date`, an optional `note`, `contentHash` = SHA-256 of the canonical JSON (sorted keys, no whitespace) of `plan` without `$schema`, `decided` and `question`, and `plan`, the plan as it was: these never change (a version that does not hold together is `E_PLAN_VERSION_INVALID`, and does not count). The days it was exported for the client are added to `sends[]` (`date`, `format`), and the client's validation to `validation` (`by`, `date`, `reference`). A person makes a version (`elabora plan version`) and records a validation (`elabora plan approve --version Vn`, the latest by default), never an agent (`E_PLAN_PERSON_ONLY`). Exporting the plan's document shows a version (the latest by default) or the working copy, records the send on the version, and never makes one. **State.** The plan's state follows from its versions: without a validated version it is a draft (`W_PLAN_DRAFT`; release builds need one: `E_PLAN_NOT_APPROVED`); when the working copy is the latest validated version it is approved; otherwise it changed since (`W_PLAN_MODIFIED_SINCE_VALIDATION`, a warning: a release build lists the changes in its report and proof dossier). A text kept `verbatim` in the validated version that changed since is flagged (`W_PLAN_VERBATIM_CHANGED`). What changed is computed, never written: `planDiff` matches the elements of two plans by their ids (added, removed, moved, an item's part changed, each field, texts word by word), from the latest validated version (the app's marks) or from the latest version (what is in no version yet); `elabora plan diff`. **Notes for the client.** `plan-versions/notes.json` (schema `plan-notes`) holds the author's notes on changes in no version yet, one per change (`target`: its key in the diff, `item:ITEM-3`; `text`). The next version takes those whose change it holds and freezes them in its `notes[]`. The document shows them in its margin and Word as comments; packages never carry them. **Translated plans.** A translated course (§13) has its own plan, generated from the source plan; its `translationOf` records the source plan's id, content hash and language. It is approved on its own (`elabora translate approve`): the translated course holds the approval as its validated version V1 while the source plan and its translation keep their content. **Coverage rules.** Every screen `covers` at least one plan item; every plan item is covered by at least one screen (`E_PLAN_ITEM_UNCOVERED`). A validated text is used through `textRef` on a screen covering its item; a validated question through `questionRef`. Copies are not accepted as uses. ## 4. Native layer: `course.json` and screens ### 4.1 `course.json` `format`, `id`, `title`, `language` (BCP 47), `version` (semver), `sections[]` (each lists its screen ids in learner order), `variables[]`, `speakers[]` (the voices of the narration, §4.7, and the characters of dialogues, §4.9), `theme` (charter `tokens` checked for WCAG 2.2 AA contrast, with the player's `player.*` and the dialogues' `dialog.*`, `custom` tokens, free `stylesheet`, embedded `fonts` (one entry per file: `family`, `src`, `weight`, `style`, and `unicodeRange` for a face split into subset files, latin and latin-ext), named `styles` (each `{ "label", "description" }`, the name authors pick it by and what it is for, or the description alone), `backdrop` (its `variants` written the same way); see [`docs/design.md`](docs/design.md)), `presentation` (`scroll` or `slides`, content widths in px at the reference window, `fit` sizes for slides: `reference` 1600x900 and `minimum` 1280x720 by default; see [`docs/design.md`](docs/design.md) §2), `navigation` (`linear`/`free`, `lockUntilComplete`), `player` (the learner's player: two bars of items, §4.8), `resources[]`, `glossary[]` and `credits[]` (what the player's Resources, Glossary and « IA et crédits » show, §4.8), `sounds` (interface sounds, music and ambiences, §4.12), `completion` (`reportAs`, `masteryScore`), `tracking`, `delivery` (`mediaQuality`: `high`, the default, ships the media masters; `medium` and `low` ship renditions encoded from them for LMS size limits; the presets are in [`docs/architecture.md`](docs/architecture.md), *Media*), `ui` (label overrides). ### 4.2 Screens A screen has `id` (equal to its file name), `title`, `covers`, `blocks[]` in reading order, optional `layout` (a built-in screen layout, `opening` (D63), or a screen-level course component: a template with named slots; blocks choose a `slot`) with its `layoutProps`, `style` (named style of the theme), `layers[]` (overlays opened by events, like Storyline layers: `id`, `title`, `presentation` `dialog` or `panel`, `blocks[]`, and an optional `narration`, which gives the layer a voice and a timeline of its own, §4.7) and `events[]`. `completeWhen` is `viewed` (default), `interactions-done` (every quiz, fill-in, sort and decision answered, every reflection saved, every dialogue's first run ended, every free object completed; blocks with `optional: true` aside) or `action` (only by a `complete-screen` action). `continueRevealsSteps: false` leaves the steps of the screen to its events (`reveal-step`): Continue no longer reveals them. `steps` says how each step opens, keyed by step number: `opens` `continue` (default: a Continue button in the page in scroll presentation, like the continue dividers of Rise; Next relabelled Continue in slides) `answered` (by itself once every activity of the steps above is answered, right or wrong, like content after a knowledge check) or `explored` (Continue, or Next in slides, is shown but locked until every activity of the steps above is answered and every control of their blocks is visited, optional blocks aside; locked, it says what is left), and `label`, the text of its Continue button. Screens with `required: false` do not count for completion. `narration` gives the screen a voice and a timeline (§4.7). ### 4.3 Blocks `{ "id", "type", "props", "blocks"?, "hidden"?, "step"?, "width"?, "slot"?, "style"?, "optional"?, "continuity"?, "note"? }`. `step` (blocks of a screen) holds the block back until the learner presses Continue or an event reveals it (`reveal-step`): in scroll presentation pending steps take no room, in slides they keep their place. `type` is a built-in type (below) or the id of a course component (§4.6). `width` is a layout hint in the default column (`full`, `wide`, `half`, `bleed`); two consecutive `half` blocks share a row on wide screens; `bleed` goes edge to edge of the window in scroll presentation and of the slide in slides, its text keeping the reading width (in a layout's slot it fills the slot), and a template asks for it from its root with `data-t-bleed`. `slot` places the block in the screen layout, or in a slot of the component instance holding it in `blocks`; `style` picks a named style. `optional: true` marks extra the learner may skip (a transcript, more detail): its activities and controls count neither for a step that opens once explored nor for `completeWhen: "interactions-done"`. `continuity: { "key", "duration"? }` makes blocks of different screens one thing to the learner (D65): going from one of those screens to another, a free object keeps running and moves to the arriving block's props over `duration` ms (default 700; [free-object contract §4e](docs/free-object-contract.md#4e-continuity-between-screens)), another block glides from where its counterpart was, nothing else moves, and less motion makes it a cut. Blocks sharing a key have the same type (free objects the same object), once per screen, never in a layer; a chain of free objects saves one state. Built-in catalogue 0.2: | Type | Purpose | Key props | |---|---|---| | `heading` | Section heading (levels 2–4; the screen title is level 1) | `text` or `textRef`, `level` | | `text` | Markdown subset | `markdown` or `textRef` | | `callout` | Key rule, tip, warning | `variant`, `title`, `markdown` or `textRef` | | `image` | Image from `assets/` | `asset`, `alt` or `decorative`, `caption`, `generated` | | `video` | Video played by the learner (captions when it has sound, transcript), a muted loop like an animated image (`loop`, with `alt`), or decorative | `asset`, `title`, `captions` (WebVTT), `transcript`, `loop`, `alt`, `decorative`, `poster`, `generated` | | `audio` | Audio with transcript, unless decorative | `asset`, `title`, `transcript`, `decorative`, `generated` | | `button` | Triggers `click` events | `label`, `variant` | | `accordion` | Panels (« Panneaux »): optional or parallel detail the learner opens (not practice) | `presentation` (`accordion`, `tabs`, `cards`, `stack`), `items[]` (`id`, `title`, `markdown`, `image`, `alt`, `focus`), `prompt`, `allowMultiple`, `hint` | | `math` | Displayed equation (LaTeX → MathML at build time) | `tex`, `caption`, `label` | | `quiz` | Single/multiple choice, elaborated feedback; options as text, as picture cards (`presentation: "images"`) or as zones on one picture (`"image"`, §4.10) | `questionRef`, or `stem` + `mode` + `options[]`; `scored`, `weight`, `attempts`; `presentation`, `image`, `alt`, options' `image`, `alt`, `x`, `y` | | `numeric` | Numeric answer within a tolerance, targeted feedback per misconception | `questionRef`, or `stem` + `answer` + `tolerance` + `unit` + `feedback` + `misconceptions[]`; `scored`, `weight`, `attempts` | | `fill-in` | Text with blanks, typed, chosen from menus or placed from a bank of words (§4.10) | `markdown` with blanks `[[answer\|other accepted]]`, `presentation`, `stem`, `distractors`, `ignoreAccents`, `feedback`; `scored`, `weight`, `attempts`, `showCorrectAnswer` | | `sort` | Items placed in pairs, into categories or in order (§4.10) | `presentation`, `stem`, `items[]` (`id`, `text`, `image`, `alt`, `target`), `targets[]`, `feedback`; `scored`, `weight`, `attempts`, `showCorrectAnswer` | | `reflection` | The learner's own words, or a point on a scale; never scored (§4.10) | `prompt`, `presentation` (`text`, `scale`), `maxLength`, `rows`, `model`, `download`, `scale` | | `decision` | Scenario choice with consequences | `prompt`, `options[]`, `scored`, `allowChange` | | `dialogue` | Branching conversation held in the block (§4.9) | `title`, `learner`, `mode`, `scoring`, `nodes[]` (`lines[]`, `options[]`, `next`, `end`), `endings[]`, `vars[]` | | `free-object` | Places a free object | `object`, `title`, `props` (declared values), `textAlternative`, `a11y` (`description` and `keyboard`, what screen readers say, worded for this block), `strings`, `aspectRatio`, `narrowAspectRatio`, `minHeight`, `maxHeight`, `scored`, `weight` | | `results` | Score and status | `allowRetry`, messages | | `statement` | The one idea of a page to remember (« Énoncé »); with an author, a quotation | `presentation` (`statement`, `ruled`, `quote`, `image`), `markdown` or `textRef`, `author`, `role`, `portrait`, `image`, `alt`, `decorative`, `focus`, `align` | | `divider` | A pause between the parts of a long page (« Séparateur »), decoration | `presentation` (`line`, `ornament`, `number`, `space`), `size`, `restart` | | `gallery` | Images read together (« Galerie ») | `presentation` (`grid`, `mosaic`, `carousel`, `compare`), `images[]` (`id`, `asset`, `alt`, `caption`, `focus`, `decorative`), `columns`, `ratio`, `caption`, `zoom` | | `columns` | Two or three columns of blocks (« Colonnes »), stacked on narrow screens | `count`, `widths`, `align`; slots `first`, `second`, `third` | | `speech` | A character speaking to the learner in bubbles beside its portrait (« Personnage ») | `speaker` (a speaker of `course.json`), `lines[]` (`id`, `markdown`), `side` (`start`, `end`), `kind` (`speech`, `thought`) | | `steps` | A process or a story in order (« Étapes »; a block, not the screen's `steps`), §4.11 | `presentation` (`carousel`, `timeline`, `scroll`), `items[]` (`id`, `title`, `markdown`, `image`, `alt`, `decorative`, `date`, `region`), `intro`, `summary`, `numbered`, `figure` (`replace`, `build`, `focus`), `figureImage`, `figureAlt`, `side` | | `hotspots` | Markers on one picture, each opening a text (« Image interactive »), §4.11 | `presentation` (`popover`, `side`, `below`, `tour`), `image`, `alt`, `decorative`, `focus`, `items[]` (`id`, `x`, `y`, `title`, `markdown`, `image`, `alt`), `markerStyle` (`number`, `icon`), `icon`, `prompt` | `image` also takes a `presentation` (`centered`, the default, `wide`, `band`, `beside`, `over`) with `focus`, `title` and `markdown` (beside, over), `side` and `share` (beside), `height` (band, over), `zoom` (centered, wide, beside: the image opens in the player's lightbox, as a gallery's images do with `zoom`); `text` takes an `aside`, a note in the margin. **Focal point**: `focus: { "x": 0..1, "y": 0..1 }` on an image becomes its `object-position`, so crops keep the subject. Blocks with several forms name them with `presentation`, its first value the default (D63). **Panels, characters, the gallery's carousel (D63).** An `accordion`'s items are the same in its four presentations, and each is a control named by its `id` in every one (a panel opened, a tab shown, a card turned over, a card of the stack seen), so its visited state survives a change of presentation: `accordion` (native disclosures, `allowMultiple: false` one open at a time), `tabs` (the room of the tallest panel kept; in containers narrower than 560 px the same items as an accordion, the one rendered being the one in the accessibility tree), `cards` (flip cards in a grid whose cards are as tall as the tallest, the front the title and the image, the back the text; two to a row on phones) and `stack` (the flip cards one at a time with Previous, Next and the position; a stack opens on its first card). An item's image needs `alt`, `""` when decorative. A `speech` block's speaker gives its name, colour and look (a character's SVG framed on its face and at rest, a portrait picture, else its initial); each line reads « Name: text » to screen readers, the written name and the portrait hidden from them. A `gallery` `carousel` shows one image whole in a frame of `ratio`, its caption, Previous, Next, a thumbnail per image (wide containers) and the position, in the room of the tallest. With `zoom`, the images of a gallery (but `compare`) and an image open in the lightbox, with previous and next between a gallery's. Checks: `W_ITEMS_MANY` (tabs over 7, cards over 12, a gallery's carousel over 5), `W_TABS_LABEL_LONG` (over 24 characters), `E_SPEECH_SPEAKER`. **Converting a block (« Transformer en… », D63).** A block becomes another presentation of its type, or another type that holds the same content, in place: panels, steps, an interactive picture and a gallery (when its items have pictures) into one another, panels into a sort in pairs, steps into a sort in order or the charts `process` and `milestones`, `statement`, `callout` and `text` into one another, an image and a gallery of one image, the bulleted or numbered list of a text into panels or steps. The block's id and its items' ids are kept, and items are never reordered (a sort's placements are saved by index), so visited controls keep their names and translation units whose text moves to another prop follow it; what a conversion keeps, loses (learner progress included: a panel's visited mark has no place in a sort) and leaves to write is said before anything is converted, and what does not fit the target (too many items, a text too long, a picture missing) is refused with its reason (`E_CONVERT_REFUSED`). The command is `convert_block` (CLI `elabora convert`, MCP `elabora_convert_block`, the engine's `conversions` request); for the lock it is a content update like any other. **Screen layouts.** A screen's `layout` names a built-in layout (`layouts/.schema.json` holds its props) or a screen-level course component. Built-in 0.2: `opening` (« Ouverture »), the head of a lesson then its page, `presentation` `title`, `band`, `split` or `cover`, props `lead`, `image`, `alt`, `decorative`, `focus`, `duration` (the page's reading time, computed by the build), slots `question` (a question before the lesson) and `body` (default). Course components may not take a built-in layout's name; they may fork one. **Markdown subset.** CommonMark without raw HTML and without images (use image blocks), plus tables and maths: `$…$` inline and `$$…$$` display, in LaTeX, rendered as MathML at build time (no script at runtime; read by screen readers). Write a literal dollar as `\$`. Links to external sites open in a new tab. Text marked `x-translatable` in the schemas is what translation tools extract. Editors lay a block's settings out from its schema: `x-group` names the section a setting goes in (`question`, `options`, `scoring`, `data`, `figure`, `markers`; without one, its content), `x-advanced` marks one authors rarely change. **Generated media.** Images, video and audio produced by an AI model carry `generated: true`; the player marks them, its « IA et crédits » names them, and the proof dossier lists them (AI Act, art. 50). **Glossary links.** A Markdown link to `glossary:` (`[passerelle](glossary:gateway)`) names an entry of `course.json` `glossary`: the player shows its definition in a tooltip when the word is hovered or focused, and opens the Glossary there when it is followed. An id the glossary does not have is `E_GLOSSARY_TERM_UNKNOWN`. ### 4.4 Events `{ id, description?, on, if?, do, else? }` — when the trigger fires and every condition holds, run `do`; otherwise `else`. `do` may be empty: an event being written, its trigger chosen before its actions, does nothing until it has one (`W_EVENT_NO_ACTION` while `else` has none either). - Triggers: `screen.enter`; `click` (a control of the block: a button block, or a button, tab, disclosure, sequence item, flip card, details or element brought into view of a component; `name` filter for one control); `quiz.submitted` (quiz, numeric, fill-in or sort block, `result` filter: a fill-in or a sort is correct when all its blanks or items are); `decision.selected` (decision, `option` filter); `object.event` (free-object block, `name`, `where` payload filter); `variable.changed`; `layer.closed`; `timeline.reached` (`at`, an anchor (§4.7): playback of the screen's timeline crosses the start or end of a line, a word of it, seconds from a step's start on a screen without narration; never on a seek, again when the learner replays the passage; a line of a layer's narration names that layer's timeline, and `layer` with `at.seconds` counts from the opening of a layer without narration); `timeline.ended` (playback reaches the end of the timeline; with `layer`, the end of that layer's timeline: `hide-layer` there closes a layer once it has spoken); `media.ended` (an audio block, or a video that is not a loop, plays to its end); `dialogue.started`, `dialogue.node` (`node`), `dialogue.line` (`line`), `dialogue.chosen` (`node`, `option`), `dialogue.ended` (`ending`) for a dialogue block (§4.9). - Conditions, all required: `{ variable, op: eq|neq|gt|gte|lt|lte, value }`, or `{ visited, name? }`: the learner has used every control of a block of the course (or the control `name`); or `{ dialogue, ending | chosen | score | done }`: what the scored run of a dialogue block of the course gave. A control is visited once used; a tab or disclosure once its content is shown. The visit is recorded before the click's events run. - Actions: `go-to` (screen id, `next`, `previous`), `show-layer`, `hide-layer` (without `layer`: the layer open on top, a dialog before a panel, the last opened first; for a Close button inside a layer; its `layer.closed` fires as for any other), `show-block`, `hide-block`, `reveal-step` (the steps of the screen up to `step`, as Continue would; a step already shown takes the focus again), `set-variable`, `increment-variable`, `complete-screen`, `set-object-props` (declared props only), `exit-course`, `pause-timeline` and `play-timeline` (the timeline of the screen; a modal layer pauses it and resumes it by itself; with `layer`, the timeline of that layer while it is open), `seek-timeline` (`to`, an anchor: the playhead goes there as a seek, firing nothing it passes; a moment in a later step reaches that step; with `layer`, or to a line of a layer's narration, that layer's timeline), `play-media` and `pause-media` (an audio or video block; playing one pauses the narration), `start-dialogue`, `goto-dialogue` (`node`) and `restart-dialogue` (a dialogue block, §4.9). Targets of triggers and of layer/block actions belong to the same screen. Controls are named in the component template: `data-t-click="name"` (the name may be bound to a prop, one per item of a list), `data-t-tab="k"`, `data-t-toggle="k"`, and the primitives' items of a sequence (`data-t-item="k"`), flip cards (`data-t-flip="k"`), disclosures (`
`) and elements visited once in view (`data-t-reveal="k"`); an unnamed `data-t-click` and the `button` block have no name. Names are checked on the rendered instance (`E_EVENT_TARGET`, `E_VISITED_TARGET`); a button without a click event that hears it is `W_DEAD_BUTTON`. ### 4.5 Variables `{ id, type: boolean|number|string|choice, default, maxLength (strings), options (choice), minimum, maximum, persist }`. Persisted variables are saved for resume and count in the suspend data budget, so strings must declare `maxLength`. ### 4.6 Components Every type is a component: built-in types are components shipped with Elabora (block types, and the screen layout `opening`), and a course defines more in `components//` — block types (`level: "block"`) and screen layouts (`level: "screen"`). A component has a props schema (strings with `x-kind`: text, markdown, tex, asset, token), named slots, a template rendered at build time (bindings, `data-if`, `data-each`, slots, behaviour hooks, headings that follow the page with `data-t-heading`, and the player's primitives: one item at a time, flip cards, the lightbox, one part open at a time, details and elements visited once in view, D63; no script) and a stylesheet (cascade layer `elabora.components`, over the theme's rules and under its `@layer overrides` blocks). A component may **extend** another (a fork remembers its parent and inherits what it does not redefine); a fork of `quiz`, `numeric`, `decision`, `dialogue` or `results` keeps its behaviour — scoring, saved state, SCORM records, focus and announcements stay in the player — so learner state is keyed as for the built-in. Components are not scored by themselves: activity blocks can sit in their slots. Every component has a **fallback** in native blocks (declared, or generated from its props), used by exports, the client view, translation and detach. Courses copy components from libraries with their origin (pinned) and upgrade them explicitly; when a definition changes the shape of its props, `migrations.mjs` steps migrate every instance, checked before anything is written. Details: [`docs/components.md`](docs/components.md). ### 4.7 Narration and timeline Every line a voice says is a **voice line** (`defs.schema.json` `voiceLine`): `id`, `speaker`, `text`, `delivery`, `pronunciations`, as below. The lines of a screen's narration add `step` and `pauseBefore`; those of a layer's narration add `pauseBefore`; those of a dialogue add their own fields (§4.9: a line with a speaker, and the learner's answers with `learnerVoice`, named `.