diff --git a/AGENTS.md b/AGENTS.md index a06eb92d..a6d247d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2463,7 +2463,11 @@ one row each; an LMS added here gets a row there. 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 `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 state is written + 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 + does not follow what is written in the session would have had every new question written over + the one before. Moodle counts as it is written, and kept one attempt's answers from two sessions + on indexes 0 and 1 (checked 2026-11-04). The state is written and committed with each answer as well as with each of the content's saves, since content that keeps no state of its own sends no `userdata`, and its questions would otherwise take a new index in every session; where the state cannot be written, the answer is still committed (both @@ -2689,8 +2693,8 @@ frames the launch page, as Moodle's player does. It covers: - the quiz's four answers as interactions, and, through dispatched `xapi` events, the id from the words and from the key, the second id for the same words, kept in a later session, the type map, the 255 cut, the result from `success` and from the score, the questions written and - committed with each answer, one index per question across a retry and a second session, and an - attempt started over; + committed with each answer, one index per question across a retry and a second session, an + attempt started over at a launch, and an LMS whose count stays at what it loaded at launch; - a state that fits only compressed, one that does not fit at all and the notice said once, both notices' live regions on the page from the start, a write the LMS refuses, and a launch page without the compressor, which writes the state plain; diff --git a/packages/embed/scorm/scorm.js b/packages/embed/scorm/scorm.js index f1d812ff..ae816d3e 100644 --- a/packages/embed/scorm/scorm.js +++ b/packages/embed/scorm/scorm.js @@ -304,12 +304,22 @@ player.addEventListener('userdata', (event) => { * column per interaction index for every learner. So a question keeps one index, written over * when it is answered again, rather than taking a new one on every attempt, which would set one * learner's columns against another's. The index and the id come from the questions kept with - * the state, after what the LMS already counts; a new attempt, where the LMS counts none, starts - * them again. They are kept with each answer, not only with the content's own saves, since + * the state, after what the LMS counted at launch; a new attempt, where the LMS counts none, + * starts them again. They are kept with each answer, not only with the content's own saves, since * content that keeps no state of its own sends none. SCORM 1.2 lets the content write the fields * and never read them, which the report does. */ +/** + * What the LMS counts of this attempt's interactions, read once, at launch, since an attempt the + * LMS starts over can only start there: fewer than the questions kept is such an attempt, which + * starts them again; more, interactions this page has no record of, which new questions go after. + * Within the session the questions kept are the record, so an LMS whose count does not follow what + * is written, or that counts none, does not put every new question on one index (#130). + */ +const launchCount = Math.max(0, Number(get('cmi.interactions._count')) || 0) +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. @@ -318,16 +328,13 @@ player.addEventListener('userdata', (event) => { */ function interactionFor(statement) { const key = questionKey(statement) - const count = Math.max(0, Number(get('cmi.interactions._count')) || 0) - // The LMS counts fewer than the state names: a new attempt, which starts them again. - if (questions.length > count) questions = questions.slice(0, count) 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}` - const index = Math.max(questions.length, count) + const index = Math.max(questions.length, launchCount) questions[index] = [key, id] return { index, id } } diff --git a/packages/embed/tests/scorm.test.ts b/packages/embed/tests/scorm.test.ts index 5c95225d..c5cefd53 100644 --- a/packages/embed/tests/scorm.test.ts +++ b/packages/embed/tests/scorm.test.ts @@ -250,12 +250,10 @@ const LMS_PAGE = ` window.API = { LMSInitialize: record('LMSInitialize', () => 'true'), LMSFinish: record('LMSFinish', sent('LMSFinish')), - // The interactions' count, which SCORM 1.2 lets the content read: one past the highest index written. + // The interactions' count, which SCORM 1.2 lets the content read: one past the highest index + // written, or, for an LMS whose count does not follow what is written, what it counted at launch. LMSGetValue: record('LMSGetValue', (element) => { - if (element === 'cmi.interactions._count') { - const indexes = Object.keys(window.values).map((key) => /^cmi\\.interactions\\.(\\d+)\\.id$/.exec(key)).filter(Boolean).map((match) => Number(match[1])) - return String(indexes.length ? Math.max(...indexes) + 1 : 0) - } + if (element === 'cmi.interactions._count') return String(window.lagging ? window.launchCount : interactionCount()) return window.values[element] ?? '' }), // An LMS that refuses the saved state, when a test says so. @@ -269,8 +267,13 @@ const LMS_PAGE = ` LMSGetErrorString: () => '', LMSGetDiagnostic: () => '' } + function interactionCount() { + const indexes = Object.keys(window.values).map((key) => /^cmi\\.interactions\\.(\\d+)\\.id$/.exec(key)).filter(Boolean).map((match) => Number(match[1])) + return indexes.length ? Math.max(...indexes) + 1 : 0 + } // A launch after a suspended session resumes it, as the LMS says with cmi.core.entry. window.launch = (path) => { + window.launchCount = interactionCount() window.values['cmi.core.entry'] = window.values['cmi.core.exit'] === 'suspend' ? 'resume' : window.calls.length ? '' : 'ab-initio' document.getElementById('sco')?.remove() const frame = document.createElement('iframe') @@ -528,20 +531,27 @@ describe('in an LMS', () => { await context.close() }) + /** A statement about the part `sub`, as the core writes one, dispatched as the element dispatches it. */ + const answer = (sco: Frame, sub: string, text: string, definition: Record = {}, result: Record = {}) => + sco.evaluate(({ verb, sub, text, definition, result }) => { + const statement = { + verb: { id: verb }, + object: { id: `http://lms.example/package.h5p?subContentId=${sub}`, definition: { description: { 'en-US': text }, interactionType: 'choice', correctResponsesPattern: ['0[,]2'], extensions: { 'http://h5p.org/x-api/h5p-subContentId': sub }, ...definition } }, + result: { response: '0[,]1', success: false, score: { raw: 0, max: 2 }, duration: 'PT12.5S', ...result } + } + ;(document.querySelector('h5p-player') as HTMLElement).dispatchEvent(new CustomEvent('xapi', { detail: { statement, verb } })) + }, { verb: 'http://adlnet.gov/expapi/verbs/answered', sub, text, definition, result }) + + /** Ends the session as the page going does, and waits for the LMS to hear this session's finish. */ + const leave = async (page: Page) => { + const before = await page.evaluate(() => (window as unknown as { calls: string[][] }).calls.length) + await page.evaluate(() => (window as unknown as { leave: () => void }).leave()) + await page.waitForFunction((before) => (window as unknown as { calls: string[][] }).calls.slice(before).some((call) => call[0] === 'LMSFinish'), before) + } + it('writes each answer as an interaction, one index per question, written over when answered again', async () => { - const ANSWERED = 'http://adlnet.gov/expapi/verbs/answered' const { context, page } = await lmsPage() const first = await launch(page) - /** A statement about the part `sub`, as the core writes one, dispatched as the element dispatches it. */ - const answer = (sco: Frame, sub: string, text: string, definition: Record = {}, result: Record = {}) => - sco.evaluate(({ verb, sub, text, definition, result }) => { - const statement = { - verb: { id: verb }, - object: { id: `http://lms.example/package.h5p?subContentId=${sub}`, definition: { description: { 'en-US': text }, interactionType: 'choice', correctResponsesPattern: ['0[,]2'], extensions: { 'http://h5p.org/x-api/h5p-subContentId': sub }, ...definition } }, - result: { response: '0[,]1', success: false, score: { raw: 0, max: 2 }, duration: 'PT12.5S', ...result } - } - ;(document.querySelector('h5p-player') as HTMLElement).dispatchEvent(new CustomEvent('xapi', { detail: { statement, verb } })) - }, { verb: ANSWERED, sub, text, definition, result }) await answer(first.sco, 'a', 'Which rivers cross Germany?') // The question and its id go with the state as it is answered, and are committed: content that @@ -590,8 +600,7 @@ describe('in an LMS', () => { ['c', 'c'], ['d', 'other'] ]) - await page.evaluate(() => (window as unknown as { leave: () => void }).leave()) - await page.waitForFunction(() => (window as unknown as { calls: string[][] }).calls.some((call) => call[0] === 'LMSFinish')) + await leave(page) const second = await launch(page) // The second of two questions with the same words, answered first this time, keeps its own id. await answer(second.sco, 'b', 'Which rivers cross Germany?', {}, { response: '2' }) @@ -600,18 +609,41 @@ describe('in an LMS', () => { expect(kept).toMatchObject({ 'cmi.interactions.1.id': 'which-rivers-cross-germany-2', 'cmi.interactions.1.student_response': '2', 'cmi.interactions.4.id': 'a-new-one' }) expect(kept['cmi.interactions.5.id']).toBeUndefined() - // An attempt the LMS started over, its interactions gone: they start again from the first index. + // An attempt the LMS started over, which it does at a launch, its interactions gone: they start + // again from the first index. + await leave(page) await page.evaluate(() => { const lms = window as unknown as { values: Record } for (const key of Object.keys(lms.values)) if (key.startsWith('cmi.interactions.')) delete lms.values[key] }) - await answer(second.sco, 'e', 'A new one', {}, { response: '1' }) + const third = await launch(page) + await answer(third.sco, 'e', 'A new one', {}, { response: '1' }) kept = await values(page) expect(kept).toMatchObject({ 'cmi.interactions.0.id': 'a-new-one', 'cmi.interactions.0.student_response': '1' }) expect(kept['cmi.interactions.1.id']).toBeUndefined() await context.close() }) + it('keeps one index per question where the LMS counts only what it loaded at launch', async () => { + // An LMS whose count does not follow what is written in the session (#130): the bridge reads it + // once, at launch, and keeps its own record from there. + const { context, page } = await lmsPage() + await page.evaluate(() => { (window as unknown as { lagging: boolean }).lagging = true }) + const first = await launch(page) + for (const sub of ['a', 'b', 'c']) await answer(first.sco, sub, `Question ${sub}`) + let kept = await values(page) + expect([0, 1, 2].map((index) => kept[`cmi.interactions.${index}.id`])).toEqual(['question-a', 'question-b', 'question-c']) + + // The next session of the attempt: the count it loaded, and new questions after it. + await leave(page) + const second = await launch(page) + await answer(second.sco, 'b', 'Question b', {}, { response: '2' }) + for (const sub of ['d', 'e']) await answer(second.sco, sub, `Question ${sub}`) + kept = await values(page) + expect(kept).toMatchObject({ 'cmi.interactions.1.student_response': '2', 'cmi.interactions.3.id': 'question-d', 'cmi.interactions.4.id': 'question-e' }) + await context.close() + }) + it('plays an export without its libraries from the parts in the zip, and only those', async () => { const { context, page } = await lmsPage() served.length = 0