0.24.0 - parametric exercises (schema 1.14), docs on Pages, hotspot + parsons

[0.24.0] - 2026-09-15

Parametric exercises: variables on any exercise, schema 1.14 (engine#151)

The last row of the comparative analysis still marked Missing. An exercise
may declare variables: SAMPLED (min/max, optional step) or COMPUTED
(expression over earlier variables, optional tolerance), and reference
them as {{name}} from any of its string fields; the consumer draws,
computes, substitutes and grades per attempt, the engine checks the
contract and never evaluates (rules E-VAR-KIND, E-VAR-DUP,
E-VAR-RANGE, E-VAR-EXPR, E-VAR-UNDEFINED, E-VAR-REF,
W-VAR-UNUSED). The expression language is deliberately small (decimal
numbers, names, + - * /, parentheses, unary minus). This could not be an
ext_payload extension because the references live in core fields.
x-schema-version 1.13 to 1.14 in both schemas (lockstep). Additive:
content without variables validates unchanged; from 1.14 on a literal
{{ in an exercise string field is reserved for references. See
docs/lesson-format.md#variables-parametric-exercises.

Rendered docs on the Pages site (engine#152)

The site published only the schema and the TypeDoc API; the Markdown
documentation under docs/ was reachable only by browsing the repository,
and an external benchmark that read the site concluded the six core exercise
types were all there is. npm run docs:site (scripts/build-docs-site.mjs,
marked as a dev dependency) now renders the top-level docs/*.md to
/docs on the site with GitHub-style heading ids, sibling links rewritten
to the rendered pages, links into the repository pointed at GitHub, and
mermaid fences rendered client-side. docs/blog and docs/proposals stay
repository-only.

Two new reference extensions: hotspot, parsons (engine#149)

docs/comparative-analysis.md benchmarked the engine's exercise types
against Moodle, H5P, QTI 3.0, Canvas and Duolingo and listed six gaps. Three
of them (ordering, categorization, audio input) already had reference
extensions; the doc now says so. The two that were genuinely missing ship
here: ext:ref-hotspot (an image with rect/circle zones in percentage
coordinates, exactly one correct, graded by point-in-zone hit test) and
ext:ref-parsons (a program's lines with per-line indent, graded on order
AND indentation; deliberately no uniqueness rule, since real code repeats
statements). Both follow the self-contained-ext_payload shape (engine#68).
ext:ref-ordering gained the reference lesson it was the only extension
without. See docs/extensions.md.

Author guidance for explanation (engine#147)

docs/lesson-format.md now says what a good post-answer explanation
CONTAINS, not only when it is shown: a one-sentence rule in the learner's
source language, a word-by-word gloss of the target sentence, two or three
further examples, and an optional typical mistake, with a complete worked
example and notes on the character budget, which exercise types benefit,
and how to avoid repeating one rule across a whole lesson. Documentation
only; the field stays free Markdown. A structured shape is deferred until
content written under the convention shows what authors actually use.