Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 31 additions & 8 deletions design/scorm.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,20 +53,43 @@ one row each; an LMS added here gets a row there.
both again and calls `LMSFinish`.
**Each answer goes into `cmi.interactions`** (#124, 2026-11-04, asked for by two of three
commenters on the Reddit demand check): every `answered` statement the element relays, by the
part's `subContentId`, with the question's words as the id, since 1.2 has no description field
and the id is what a report shows (a slug in printable ASCII, which 1.2's `CMIIdentifier`
allows and nothing else; the key for a question with no words; `-2` on a second question with
the same words), the xAPI type as 1.2 names it (`long-fill-in` as `fill-in`, `other` and an
unknown type left out), the pattern and the response cut to 255 (`CMIFeedback`; H5P's `0[,]2`
goes in as it is, which Moodle takes), `correct` or `wrong` from `success`, or from the score
part's `subContentId`, with an id a person reads, since 1.2 has no description field and the id
is what a report shows: the question's number, its index from 1, and its first words, as text
(markup out, character references read, or `’` came out as `rsquo`), 40 characters cut
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
at a word, or at the 40th where the first word runs longer, in letters, digits and `_` alone, as in `Q3_which_rivers_cross_germany`; the number
alone where the words have no Latin letters. After the form a commenter on the Reddit SCORM
post uses, `L2_Q3_refund_case` (2026-11-08): 1.2 calls a `CMIIdentifier` alphanumeric, and an
LMS that holds it to that refuses the colon and the slash that the earlier fallback for a
question with no words, its activity's URL, could carry. The number keeps two questions with
the same words apart, where a `-2` did until then; in content answered out of order, a Course
Presentation or a book, it follows the order of answering, as the index does. Then the xAPI
type as 1.2 names it (`long-fill-in` as `fill-in`, `other` and an unknown type left out), and
the pattern and the response cut to 255 (`CMIFeedback`) **only where they are the learner's
own text or number, `fill-in` and `numeric`**: 1.2 holds a choice, true-false, matching or
sequencing answer to single characters, which H5P's `0[,]2` and `true`, written in 2004's
notation, are not. Moodle took them as they are, but a strict LMS refuses them and LMSs read
1.2's form differently, the same commenter's reason to send none, so since 2026-11-08 those
answers carry their result alone: a conformance fix, as `docs/compatibility.md` names one.
The two that keep theirs are written as a person reads them (`scorm12Answer`, the same day,
the owner's call when Moodle's report was found to show `{case_matters=false}stored[,]Range`):
the right answer without the `{case_matters=…}`, `{lang=…}` it opens with, a fill-in's blanks
listed with commas in place of `[,]`, every fill-in type in the pack writing them that way, so
`stored, Range`; and a numeric only where it is a number, 1.2's `CMIDecimal`, not 2004's range
`1[:]5`, though no library in the pack writes `numeric`. 2004 keeps the notation, its own.
Then `correct` or `wrong` from `success`, or from the score
where the content says nothing, as Fill in the Blanks does not (full marks, none, or the marks
themselves, a number 1.2 takes there), `neutral` with neither, the marks as `weighting`,
`result.duration` as `latency`, the time of day. **One index per question, written over on a
retry**, read in Moodle's code: its interactions report has one column per index for every
learner (`get_scorm_question_count` takes the highest index found), so an entry per attempt
would set one learner's columns against another's. The index and the id come from the
would set one learner's columns against another's. Written over in 1.2, a response or a right
answer the new answer has none of is emptied, not left (the same day, from the PR's review):
1.2 keeps a field nothing writes again, so a fill-in typed then and left empty now, or a
choice's response in H5P's notation from a zip before the answers were held to their types,
would stand beside the new result. The index and the id come from the
questions kept with the state (`questions` in `suspend_data`, a `[key, id]` per index, so that
the second of two questions with the same words keeps its `-2` in a later session), after
a question keeps its id in a later session, and one an older zip kept keeps the id that zip
gave it), after
`cmi.interactions._count`, which 1.2 lets a SCO read and Moodle reloads from the attempt's
tracks; an attempt the LMS started over counts none, and they start again. The count is read
once, at launch, where an attempt starts over (#130): read on every answer, an LMS whose count
Expand Down
15 changes: 10 additions & 5 deletions packages/embed/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,11 +144,16 @@ package, the player and the H5P runtime, and a launch page that reports to the L

- the score out of 100, and `passed` or `failed` when the content says whether it was passed,
`completed` when it does not. The content's last result counts, as on an H5P site;
- each question's answer, as `cmi.interactions`: the question's words as the id, its type, the
answer given and the right one, `correct` or `wrong`, the marks it was worth and the time it
took. One interaction per question, written over when it is answered again, which is how
Moodle's interactions report lines learners up. SCORM 1.2 lets the content write these and
never read them; the LMS's reports do;
- each question's answer, as `cmi.interactions`: an id a report reads, the question's number and
first words, such as `Q3_which_rivers_cross_germany`, though an attempt begun under an earlier
zip keeps the ids it began with; its type, `correct` or `wrong`, the marks it was worth and the
time it took; and for an answer the learner typed, fill-in or numeric, the answer given and the
right one, as plain text up to 255 characters: `stored, Range` where H5P writes
`{case_matters=false}stored[,]Range`, and a numeric answer only where it is a number. SCORM 1.2 writes a choice, true-false, matching or sequencing
answer in a form of its own, which LMSs read differently, so those carry their result alone.
One interaction per question, written over when it is answered again, which is how Moodle's
interactions report lines learners up. SCORM 1.2 lets the content write these and never read
them; the LMS's reports do;
- the time spent in each session;
- the learner's place: the content's saved state goes into `cmi.suspend_data`, compressed, and
the next launch continues from it. SCORM 1.2 keeps 4,096 characters; compressed, a quiz's state
Expand Down
106 changes: 76 additions & 30 deletions packages/embed/scorm/scorm.js
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,10 @@ const SUSPEND_DATA_LIMIT = scorm2004 ? 64000 : 4096
* characters; in 2004 the longest the format allows, 4,000.
*/
const FEEDBACK_LIMIT = scorm2004 ? 4000 : 255
/** An interaction's id, a `CMIIdentifier`: 255 characters of printable ASCII, no spaces. */
const IDENTIFIER_LIMIT = 255
/** How much of a question's words a SCORM 1.2 id carries after its number: cut at a word, or here where the first word is longer. */
const ID_WORDS_LIMIT = 40
/** Latin letters that no decomposition takes to ASCII, as an id spells them. */
const FOLDED = /** @type {Record<string, string>} */ ({ ß: 'ss', æ: 'ae', œ: 'oe', ø: 'o', đ: 'd', ł: 'l', þ: 'th', ð: 'd', ı: 'i' })
/** What 2004 keeps of a question's words, `cmi.interactions.n.description`: 250 characters. */
const DESCRIPTION_LIMIT = 250
/** The verb of a question answered. */
Expand Down Expand Up @@ -223,6 +225,25 @@ function outcomeOf(result) {
return raw >= max ? 'correct' : raw <= 0 ? wrong : String(Math.round(raw * 100) / 100)
}

/**
* A SCORM 1.2 answer or right answer, for the two types 1.2 takes them for, as a report shows them
* to a person. H5P writes both in 2004's notation, which xAPI took over and 1.2 has not: a fill-in's
* right answer opens with `{case_matters=false}` and the like, and both part a blank from the next
* with `[,]`, so 1.2 gets `stored, Range` for `{case_matters=false}stored[,]Range`; the learner's
* own words are kept as typed. A numeric's is a number, 1.2's `CMIDecimal`, and anything else, such
* as 2004's range `1[:]5`, is not written. Nothing is written for what comes out empty.
* @param {unknown} text
* @param {string} type `fill-in` or `numeric`
* @param {boolean} right whether it is the right answer, whose modifiers go
* @returns {string | null}
*/
function scorm12Answer(text, type, right) {
if (typeof text !== 'string') return null
if (type === 'numeric') return /^-?(\d+(\.\d*)?|\.\d+)$/.test(text.trim()) ? text.trim() : null
const plain = (right ? text.replace(/^(\{[^{}]*\})+/, '') : text).split('[,]').join(', ')
return plain === '' ? null : plain
}

/**
* Which question a statement is about: the part's id, which the core writes on every statement
* about a part; the content's own, for a question that is the whole package, has none.
Expand All @@ -236,7 +257,9 @@ function questionKey(statement) {

/**
* The question's words, from the statement's description in the content's language, else the
* first it gives; a question type that writes markup there has it taken out.
* first it gives, as text: a question type that writes markup there has it taken out, and the
* character references it writes, `&nbsp;` and `&rsquo;` among them, read, or a 1.2 id would
* spell them out (`Q1_don_rsquo_t`) and a 2004 description show them as they are.
* @param {AnsweredStatement} statement
* @param {string} language
*/
Expand All @@ -245,32 +268,38 @@ function questionText(statement, language) {
if (!description || typeof description !== 'object') return ''
const map = /** @type {Record<string, unknown>} */ (description)
const text = map[language] ?? map['en-US'] ?? Object.values(map)[0]
return typeof text === 'string' ? text.replace(/<[^>]*>/g, ' ') : ''
if (typeof text !== 'string') return ''
const read = new DOMParser().parseFromString(text.replace(/<[^>]*>/g, ' '), 'text/html').documentElement.textContent ?? ''
return read.replace(/\s+/g, ' ').trim()
}

/**
* An interaction's id. In SCORM 1.2 it is what a report shows, since 1.2 has no description: the
* question's words as a slug in printable ASCII, else the question's key with anything else taken
* out, else `question`. In 2004, where the words go into the description, an identifier, as 2004
* asks one to be a URI: the part's id as a `urn:uuid:`, else the activity's own, else a `urn:h5p:`.
* question's number, its index from 1, and its first words, as in `Q3_which_rivers_cross_germany`,
* in letters, digits and `_` alone, which every LMS takes as a `CMIIdentifier`; the number alone
* for a question with no words in Latin letters. The number keeps two questions with the same
* words apart. In 2004, where the words go into the description, an identifier, as 2004 asks one
* to be a URI: the part's id as a `urn:uuid:`, else the activity's own, else a `urn:h5p:`.
* @param {string} text
* @param {string} key
* @param {number} index
*/
function interactionId(text, key) {
function interactionId(text, key, index) {
if (scorm2004) {
if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(key)) return `urn:uuid:${key.toLowerCase()}`
if (/^[a-z][a-z0-9+.-]*:[\x21-\x7e]+$/i.test(key) && key.length <= 4000) return key
return `urn:h5p:${encodeURIComponent(key)}`
}
const slug = text
const words = text
.toLowerCase()
.replace(new RegExp(`[${Object.keys(FOLDED).join('')}]`, 'g'), (letter) => FOLDED[letter] ?? '')
.normalize('NFKD')
.replace(/[̀-ͯ]/g, '')
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '')
.slice(0, 80)
.replace(/-+$/, '')
return (slug || key.replace(/[^\x21-\x7e]/g, '')).slice(0, IDENTIFIER_LIMIT) || 'question'
.replace(/[^a-z0-9]+/g, '_')
.replace(/^_+|_+$/g, '')
const cut = words.lastIndexOf('_', ID_WORDS_LIMIT)
const shown = words.length <= ID_WORDS_LIMIT ? words : words.slice(0, cut > 0 ? cut : ID_WORDS_LIMIT)
return shown ? `Q${index + 1}_${shown}` : `Q${index + 1}`
}

/** The package's build, as the writer stamped it: what saved state is kept against. */
Expand Down Expand Up @@ -434,47 +463,64 @@ if (questions.length > launchCount) questions = questions.slice(0, launchCount)

/**
* The question's index and the id it was written under: those it has, else the next index and
* an id no other question has, so that two with the same words differ.
* the id that names it. A question kept by an older zip, in the state it wrote, keeps its old id.
* @param {AnsweredStatement} statement
* @returns {{ index: number, id: string }}
* @returns {{ index: number, id: string, again: boolean }} `again` for a question this attempt answered before
*/
function interactionFor(statement) {
const key = questionKey(statement)
const known = questions.findIndex((entry) => entry?.[0] === key)
if (known !== -1) return { index: known, id: /** @type {[string, string]} */ (questions[known])[1] }
const base = interactionId(questionText(statement, language), key)
const taken = new Set(questions.map((entry) => entry?.[1]))
let id = base
for (let n = 2; taken.has(id); n++) id = `${base.slice(0, IDENTIFIER_LIMIT - 1 - String(n).length)}-${n}`
if (known !== -1) return { index: known, id: /** @type {[string, string]} */ (questions[known])[1], again: true }
const index = Math.max(questions.length, launchCount)
const id = interactionId(questionText(statement, language), key, index)
questions[index] = [key, id]
return { index, id }
return { index, id, again: false }
}

/** @param {AnsweredStatement} statement */
function recordAnswer(statement) {
const { index, id } = interactionFor(statement)
const { index, id, again } = interactionFor(statement)
/** @param {string} field */
const at = (field) => `cmi.interactions.${index}.${field}`
// The id first: it is the field that makes the record; then, in 2004, the question's words, and
// the type, which 2004 needs before the pattern and the response it gives the form of.
set(at('id'), id)
if (scorm2004) {
// As text: the character references a question type writes, `&rsquo;` among them, read.
const words = (new DOMParser().parseFromString(questionText(statement, language), 'text/html').documentElement.textContent ?? '').replace(/\s+/g, ' ').trim()
const words = questionText(statement, language)
if (words) set(at('description'), words.slice(0, DESCRIPTION_LIMIT))
}
const definition = statement.object?.definition
const types = /** @type {Record<string, string>} */ (scorm2004 ? INTERACTION_TYPES_2004 : INTERACTION_TYPES)
const type = typeof definition?.interactionType === 'string' ? types[definition.interactionType] : undefined
if (type) set(at('type'), type)
// 2004 takes a pattern and a response only after the type that gives their form, and refuses
// them without one (408); 1.2 takes them as they come.
const typed = Boolean(type) || !scorm2004
// them without one (408); H5P writes them in 2004's own notation, which xAPI took over. 1.2 gets
// them only where they are the learner's own text or number, `fill-in` and `numeric`, as text a
// person reads (`scorm12Answer`): it holds a choice, true-false, matching or sequencing answer to
// single characters, which H5P's `0[,]2` and `true` are not, and LMSs part ways on those, so such
// an answer carries its result alone.
const pattern = Array.isArray(definition?.correctResponsesPattern) ? definition.correctResponsesPattern[0] : undefined
if (typed && typeof pattern === 'string') set(at('correct_responses.0.pattern'), pattern.slice(0, FEEDBACK_LIMIT))
const result = statement.result ?? {}
if (typed && typeof result.response === 'string') set(at(scorm2004 ? 'learner_response' : 'student_response'), result.response.slice(0, FEEDBACK_LIMIT))
/** @type {string | null} */
let right = null
/** @type {string | null} */
let given = null
if (scorm2004 && type) {
if (typeof pattern === 'string') right = pattern
if (typeof result.response === 'string') given = result.response
} else if (type === 'fill-in' || type === 'numeric') {
right = scorm12Answer(pattern, type, true)
given = scorm12Answer(result.response, type, false)
}
// An answer to a question answered before is written over the earlier one, and 1.2 keeps a field
// the new answer leaves out: a response the learner typed then and not now, or a choice's in H5P's
// notation from a zip before 1.2's answers were held to their types, in an attempt it began. So in
// 1.2 such a field is emptied, and the record shows nothing of another answer.
const clears = again && !scorm2004
if (right !== null) set(at('correct_responses.0.pattern'), right.slice(0, FEEDBACK_LIMIT))
else if (clears) set(at('correct_responses.0.pattern'), '')
if (given !== null) set(at(scorm2004 ? 'learner_response' : 'student_response'), given.slice(0, FEEDBACK_LIMIT))
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
else if (clears) set(at('student_response'), '')
set(at('result'), outcomeOf(result))
if (typeof result.score?.max === 'number') set(at('weighting'), String(result.score.max))
const latency = latencyOf(result.duration)
Expand Down
Loading
Loading