Repository navigation
feat(scorm): each answer as a cmi.interaction, the saved state compressed - #126
Merged
Merged
Conversation
…pressed Every `answered` statement the element relays goes into `cmi.interactions.n`: the question's words as the id, the type as SCORM 1.2 names it, the pattern and the response cut to 255, the result from `success` or from the score, the marks, the latency and the time. One index per question, kept with the state and written over on a retry, after `cmi.interactions._count`, so Moodle's interactions report lines learners up. `cmi.suspend_data` is written compressed with lz-string 1.5.0, vendored as `scorm/lz-string.js` (MIT) and shipped in the zip, the written site and the page builder's assets; a plain state from a zip up to 1.4 still reads. A state that does not fit, or a write the LMS refuses, is said once under the content and in the console. Checked in Moodle 4.5 in standard mode: the four interactions in the report, resume with the compressed state, and a 12-chapter book read to its end. Measured on 23 corpus packages: nothing above 1,040 characters compressed. Closes #124 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
There was a problem hiding this comment.
🟡 Changes recommended
The unconditional compressor fetch breaks existing bundled integrations when assets.lz is omitted and the file is unavailable under base, causing SCORM exports to fail.
4 open issues
1 file not reviewed
packages/embed/scorm/lz-string.js: Generated file
What changed in this PR
Extends the embed package’s SCORM 1.2 output with per-question reporting and compressed resume data, using the same assets in command-line and browser-built exports.
Changes:
- Records answered questions as LMS interactions, with indexes intended to persist across retries and sessions.
- Compresses saved state with lz-string, reads legacy plain JSON, and warns when saving fails.
- Updates packaging, documentation, demo integration, and asset checks.
| File | Description |
|---|---|
packages/embed/tests/build.test.ts |
Checks that generated sites include the compressor. |
packages/embed/site/scorm.html |
Documents per-question reporting. |
packages/embed/scorm/lz-string.js |
Adds the vendored compressor and MIT notice. |
packages/embed/scorm/index.html |
Loads the compressor and adds a save-warning region. |
packages/embed/README.md |
Describes interactions, compression, and save limits. |
packages/embed/package.json |
Exports the compressor asset. |
packages/embed/lib/scorm.mjs |
Supplies the compressor to command-line exports. |
packages/embed/lib/scorm-core.mjs |
Includes the compressor in ZIP entries and notices. |
packages/embed/lib/scorm-browser.mjs |
Accepts or fetches the compressor for browser exports. |
packages/embed/lib/build.mjs |
Copies the compressor into generated sites. |
packages/embed/bin/h5p-embed.mjs |
Updates CLI output to mention question answers. |
docs/compatibility.md |
Documents interaction reporting and saved-state compatibility. |
apps/demo/demo/scorm.html |
Updates reporting and compression descriptions. |
apps/demo/demo/scorm-page.js |
Supplies the compressor as a bundled asset. |
AGENTS.md |
Records the reporting, resume, packaging, and test behavior. |
Review effort: Balanced
| const files = { | ||
| launch: assets.launch ?? (await (await fetched(fetchImpl, at('scorm-launch.html'), "The launch page's template")).text()), | ||
| bridge: assets.bridge !== undefined ? asBlob(assets.bridge) : await blob(at('scorm.js'), 'The launch page\'s script'), | ||
| lz: assets.lz !== undefined ? asBlob(assets.lz) : await blob(at('lz-string.js'), 'The launch page\'s compressor'), |
| </div> | ||
| <h5p-player%LIBRARIES%></h5p-player> | ||
| <p class="notice error" id="notice" role="alert" hidden></p> | ||
| <p class="notice" id="saving" role="status" hidden></p> |
| */ | ||
|
|
||
| /** @type {Map<string, string>} the id written for each question, so two with the same words differ */ | ||
| const ids = new Map() |
| if (!initialized) return | ||
| const { statement, verb } = /** @type {CustomEvent<{ statement?: AnsweredStatement, verb?: string }>} */ (event).detail | ||
| if (verb !== ANSWERED || !statement) return | ||
| recordAnswer(statement) |
- A page that bundles the launch files and gives no compressor, as one written for 1.4 does, gets the one at `base` or a zip without it, whose page names none and whose bridge writes the state plain, rather than an export that fails on `lz-string.js`. - Each question's id is kept with its index in the state, so the second of two questions with the same words keeps its `-2` in a later session. - The state, and so the questions, is written and committed with every answer, since content that keeps no state sends no `userdata`. - The save notice and the launch page's error sit in live regions that are on the page from the start, empty, so a screen reader announces them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


Closes #124.
The SCORM zip's bridge now reports each question's answer, and keeps the learner's place in less room. Asked on Reddit whether SCORM 1.2 is enough for H5P, two of three commenters wanted per-question results in the LMS's report, and one pointed at the 4,096-character limit on resume data; all three said 1.2 by default. Both fit 1.2 as it is.
Each answer as an interaction
Every
answeredstatement the element relays becomes acmi.interactions.n: 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, 1.2'sCMIIdentifier; the part's id for a question with no words;-2on a second question with the same words), the xAPI type as 1.2 names it (long-fill-inasfill-in;otherand unknown types left out), the pattern and the response cut to 255 (CMIFeedback; H5P's0[,]2goes in as it is, which Moodle takes),correctorwrongfrom the statement'ssuccess, or from its 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), the marks asweighting, the duration aslatency, and 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, so an entry per attempt would set one learner's columns against another's. The index and the id come from the questions kept with the state (a
[key, id]per index, so the second of two questions with the same words keeps its-2in a later session), aftercmi.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 and committed with each answer too, since content that keeps no state of its own sends nouserdatato carry the questions.The state, compressed
cmi.suspend_dataholds the same{ build, entries }, plus the questions, compressed with lz-string'scompressToBase64: ASCII, as 1.2 asks, and synchronous, so the content's last save onbeforeunloadstill lands, where the browser'sCompressionStreamis asynchronous and could lose it. A state that begins with{, written plain by a zip up to 1.4, is read as it is, so a learner's place survives the upgrade. lz-string 1.5.0 is vendored asscorm/lz-string.js, npm's minified build under its MIT licence in the file's header, loaded by the launch page as a classic script; it goes into the zip, the written site (lz-string.js), the page builder'sassets(lz) and bothNOTICE.txts. A page that bundles the launch files for 1.4 and gives nolzkeeps working: it gets the compressor atbaseif there is one, else a zip without it whose page names none and whose bridge writes the state plain, as 1.4 did.Measured on the corpus, the state as the bridge writes it, plain and compressed, after a generic click-through of each package (answers chosen, Check and Next pressed; a German package's buttons it mostly missed, so these are closer to a fresh state than to a finished one):
A state under about 150 characters comes out longer compressed (base64 costs a third), and nothing came near 4,096. Three of the six books and both Branching Scenarios report no state at all: two carry Interactive Book 1.3, from before it kept one.
A failed save is said. When a state does not fit compressed, or the LMS refuses the write, the launch page shows one line under the content, once, and writes the reason to the console; until now it was skipped without a word and the last accepted state stayed, which it still does. The line, and the launch page's error, each sit in a live region that is on the page from the start, empty, as ACCESSIBILITY.md asks.
Reused
xapievents, with the verb the frame posts; nothing new in the player.public/mod/scorm/datamodels/scorm_12.js,report/interactions,report/reportlib.php) decided the index rule, the id's character set and the 255 cut.Tests
scorm.test.ts: the quiz's four answers as interactions in Chromium; through dispatchedxapievents, the id from the words and from the key, the second id for the same words, the type map, the 255 cut, the result fromsuccessand from the score, one index per question across a retry and a second session, and an attempt started over; the second id for the same words kept in a later session, the questions written and committed with the answer; a state that fits only compressed, one that does not fit at all with the notice said once, both live regions present from the start, a write the LMS refuses, a launch page without the compressor writing plain, and a plain state from a zip before this read back. The LMS stand-in answerscmi.interactions._countand can refuse a write.scorm-browser.test.tsandscorm-page.test.tshold the page's zip to the command's,lz-string.jsincluded;scorm-browser.test.tsalso builds with bundled launch files and no compressor (a zip without it, its page and NOTICE naming none), with one given, and refuses a site that lacks it;build.test.tsthe written site's files.Checked by hand: Moodle 4.5.15 in Docker, "SCORM 1.2 standard mode" on (4,096 characters), as a student in Chrome:
passed, 66.67; fourcmi.interactions_nin the attempt's tracks with the ids from the questions' words (where-was-this-quiz-unpacked, …),choice,true-false,fill-in,fill-in, the patterns, the responses (stored[,]Range[,]deflated[,]front),correctthree times andwrongonce, the weightings 1, 1, 4 and 3, latencies and times;get_scorm_question_count4; the interactions report shows the learner's row with Response 0 to 3;cmi.suspend_data376 characters, lz-string's base64;entrywasresumeand the quiz reopened on the second question;H5P.DragQuestionDropzone 0.1, which neither it nor the pack carries, as the writer has always refused): read to the last chapter, the state was 996 characters compressed (2,141 plain), nothing refused, no notice; the next launch'sentrywasresumeand the chapters' state came back.What that test found, outside this change: the book came back on its first chapter, not its last, in Moodle and in the plain player with
resume="device"alike. Interactive Book keeps its place asurlFragmentswithh5pbookid, the content id, and takes it back only when that id matches the current one; the frame's boot script gives every load a random content id (Math.random()inintegrationFor, as h5p-standalone did), so it never matches. A runtime fix, filed as Interactive Book never returns to its chapter: the frame's content id is random per load #127.Two corpus books (Interactive Book 1.3) save no state in any player: the version predates save and resume.
Docs
The embed README (what the LMS records, the limit), the SCORM page on the site and the demo,
docs/compatibility.md, AGENTS.md.🤖 Generated with Claude Code