Skip to content

feat(scorm): each answer as a cmi.interaction, the saved state compressed - #126

Merged
alekswebnet merged 3 commits into
mainfrom
feat/scorm-interactions
Nov 4, 2026
Merged

alekswebnet merged 3 commits into
mainfrom
feat/scorm-interactions

Conversation

@alekswebnet

@alekswebnet alekswebnet commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

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 answered statement the element relays becomes a cmi.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's CMIIdentifier; the part's id 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 unknown types 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 the statement's success, 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 as weighting, the duration as latency, 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 -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 and committed with each answer too, since content that keeps no state of its own sends no userdata to carry the questions.

The state, compressed

cmi.suspend_data holds the same { build, entries }, plus the questions, compressed with lz-string's compressToBase64: ASCII, as 1.2 asks, and synchronous, so the content's last save on beforeunload still lands, where the browser's CompressionStream is 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 as scorm/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's assets (lz) and both NOTICE.txts. A page that bundles the launch files for 1.4 and gives no lz keeps working: it gets the compressor at base if 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):

Package Plain Compressed
Question Set, 4 questions (the demo quiz), answered 171 184
Question Set, 8 scenarios (h5p-author's example), answered 238 204
Course Presentation, 9 packages 148 to 370 176 to 284
Interactive Book, 6 chapters and 5 questions 630 420
Interactive Book, 10 chapters and 24 questions 2,094 936
Interactive Book, 12 chapters, after the click-through 2,327 1,036

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

  • The element's xapi events, with the verb the frame posts; nothing new in the player.
  • lz-string, vendored as published; no copy of its code was written.
  • Moodle's own data model and report code (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 dispatched xapi events, the id from the words and from the key, the second id for the same words, the type map, the 255 cut, the result from success and 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 answers cmi.interactions._count and can refuse a write.

  • scorm-browser.test.ts and scorm-page.test.ts hold the page's zip to the command's, lz-string.js included; scorm-browser.test.ts also 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.ts the 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:

    • the quiz, three answers right: passed, 66.67; four cmi.interactions_n in 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), correct three times and wrong once, the weightings 1, 1, 4 and 3, latencies and times; get_scorm_question_count 4; the interactions report shows the learner's row with Response 0 to 3; cmi.suspend_data 376 characters, lz-string's base64;
    • resume: a session left after the first question wrote 220 characters, the next launch's entry was resume and the quiz reopened on the second question;
    • the end-of-book test on the corpus's longest Interactive Book that writes a SCORM zip (12 chapters, Interactive Book 1.15; the 10-chapter one is refused for 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's entry was resume and 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 as urlFragments with h5pbookid, 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() in integrationFor, 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

alekswebnet and others added 2 commits November 4, 2026 15:46
…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>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread packages/embed/lib/scorm-browser.mjs Outdated
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'),
Comment thread packages/embed/scorm/index.html Outdated
</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>
Comment thread packages/embed/scorm/scorm.js Outdated
*/

/** @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>
@alekswebnet
alekswebnet merged commit 57c6a3d into main Nov 4, 2026
8 checks passed
@alekswebnet
alekswebnet deleted the feat/scorm-interactions branch November 6, 2026 08:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SCORM: per-question results in cmi.interactions, and a resume state that fits in 4 KB

2 participants