Repository navigation
Conversation
Results (cmi.core.score.raw, cmi.core.lesson_status, interactions,
cmi.suspend_data) were only reported to the LMS when the learner clicked
Save Session (or the window unloaded). If the LMS viewer unloaded the SCO
without reliably firing onbeforeunload, nothing was reported and the
gradebook stayed empty mid-attempt.
Root cause, traced through Xerte's xttracking_scorm1.2.js + xenith.js
(content-level, not fixable in the engine files here -- the release
workflow builds the engine from the docker-container branch of
RichardoC/xerteonlinetoolkits, so engine JS edits do not persist):
- exitInteraction() (called on every page leave / quiz answer) issues
many LMSSetValue calls but NEVER calls LMSCommit.
- doLMSCommit() is called ONLY inside finishTracking(), which is called
ONLY from XTTerminate() (Save Session button / window.onbeforeunload).
- SCORM 1.2 only persists LMSSetValue to the LMS backend on LMSCommit,
so all progress stayed in the API adapter's in-memory model until
terminate. Worse, cmi.core.score.raw and cmi.core.lesson_status are
*set* only inside finishTracking(), so even a bare mid-session commit
would not update the gradebook.
Fix (content-level, no engine/vendoring change -- mirrors the
unmarkForCompletion workaround pattern):
Changes to source/data.xml + source/preview.xml (identical):
- script="..." attribute on the <learningObject> root. `script` is an
official, optional Nottingham root property (wizard data.xwd line 261:
"Add JavaScript to this project. The code will run after the project
interface has been set up but before any pages have loaded"); xenith.js
injects it once globally via $x_head.append('<script>' +
x_params.script + '</script>') (line 2269). The script:
1. Defines persist() -- replays the score/status half of
finishTracking() (cmi.core.lesson_status, cmi.core.score.raw/min/max,
cmi.core.exit, cmi.suspend_data) from the engine's own global
`state`, then calls doLMSCommit(). Guarded to be a no-op outside a
live SCORM normal session (state.initialised, scormmode === 'normal',
trackingmode !== 'none', !state.finished, doLMSCommit +
state.getSuccessStatus present) -- so play.php, xAPI, and noop
tracking are unaffected.
2. Wraps the global XTExitPage and XTExitInteraction so every page leave
and quiz answer flushes immediately -- the gradebook updates as the
learner progresses.
3. A 30s setInterval heartbeat + a pagehide listener as safety nets for
idle learners and LMS viewers that unload without events.
The attribute value uses single quotes, !== -1 instead of >= 0, and
nested if instead of &&, so it contains no XML-special characters
(& < > ") and sits raw in the XML with no escaping concerns.
Validated end-to-end through a running XOT (docker-container branch)
instance on host port 8088:
- Pushed source/data.xml + source/preview.xml into the container; both
carry the root script attribute and are byte-identical to the repo
source. The original engine JS is unchanged (no persistProgress in
/var/www/xerte/modules/xerte/scorm1.2/xttracking_scorm1.2.js).
- play.php?template_id=1 returns 200; HTML5 editor opens (200) with 44
tree nodes and no lockfile prompt.
- Editor Publish round-trip PRESERVES the script attribute in data.xml
byte-for-byte (build_lo_data loads ALL root attributes including
script; editor/upload.php process() re-adds every attribute via
addAttribute -- no filtering by wizard-declared names; makeAbsolute
only rewrites FileLocation + '...' media refs, absent from the
script). data.xml/preview.xml in the container remain identical to
the repo source after Publish.
- SCORM export is valid SCORM 1.2 (one SCO, ~13 MB) and the exported
template.xml carries the autosave script (xPersistProgress count = 1),
trackingMode="full", trackingWeight 1x7 + 21, trackingPassed="80%",
unmarkForCompletion="true" x1, 45 questions, 8 quizzes judge="true",
27 delaySecs="0", 0 empty options -- all unchanged from 0.0.5 except
the added script.
- Drove the exported package (original, unpatched engine JS) against a
SCORM 1.2 mock API harness: with the script, 5 LMSCommit calls fire
DURING progress (cmi.core.score.raw going 0 -> 100 as a quiz is
answered, lesson_status and suspend_data set, 32 interaction
setValue calls) plus 1 on terminate; WITHOUT the script, 0 commits
fire during progress and only 1 on terminate (the original bug). All
7 assertions pass (LMSInitialize, commits during progress, score.raw
+ lesson_status + suspend_data set during progress, interactions
recorded, LMSFinish once).
Trade-off: the script wraps XTExitPage/XTExitInteraction at runtime, so
it depends on those globals existing and on the engine's global `state`
object shape (getSuccessStatus/getRawScore/getMinScore/getMaxScore/
getVars) -- all stable Nottingham engine internals. If the engine is
ever patched upstream to commit on exitInteraction, this script becomes
redundant (harmless -- persist() would just call doLMSCommit a second
time, which is idempotent) and can be dropped. Do not remove or empty
the root script attribute without a replacement -- re-introducing the
terminate-only commit will silently revert to "results only on Save".
Guidance updates:
- docs/PROJECT_CONTEXT.md: added "SCORM autosave on progress (root
script attribute)" section documenting the root cause, fix, safety,
and durability; noted the root script attribute in the current-state
list; added `grep -c 'xPersistProgress'` and `unmarkForCompletion`
lines to the verification checklist.
- docs/COURSE_VERIFICATION.md: added "SCORM autosave on progress (root
script attribute)" section with the problem, fix, validation results,
and the pending LMS re-test.
Pending (convention 9 -- re-test on LMS): confirm a learner attempt now
shows the gradebook updating incrementally (not only on Save), and that
a completed attempt still reports lesson_status=passed with a non-zero
grade.
Generated with pi 0.80.6 and GLM 5.2
📖 Course content previewDownload the
|
RichardoC
added a commit
that referenced
this pull request
Sep 2, 2026
…es across sessions (#9) Fixes the four problems reported from a real LMS attempt. All four come from how `xttracking_scorm1.2.js` serialises `cmi.suspend_data`, so they are worked around from the course's root `script` property — the release workflow rebuilds the engine from upstream XOT on every build, so the engine itself cannot be patched here. ## 1. Course fails to load `getVars()` saves the resume point as `find(currentpageid)` and pushes the result unchecked (`xttracking_scorm1.2.js:271-273`). `currentpageid` is blank between leaving one page and entering the next (`exitInteraction()` clears it at line 483) and on a revisit to the Table of Contents, where `XTEnterPage()` is skipped for an already-built page. So the record held `"interactions":[null]`, and the next launch read `page_nr` off that null and threw: ``` TypeError: Cannot read properties of null (reading 'page_nr') at ScormTrackingState.setVars (xttracking_scorm1.2.js:238:64) at ScormTrackingState.initTracking (xttracking_scorm1.2.js:856:22) at XTInitialise (xttracking_scorm1.2.js:1391:15) at x_continueSetUp2 (common_html5/js/xenith.js:2275:2) ``` The exception unwinds the player's setup, so nothing renders — and because the bad value is stored in `suspend_data`, every later launch fails the same way. Two writers produced it: the autosave added in #6 flushed inside that blank window on every page exit, and the engine's own `finishTracking()` does it when a learner saves or closes on the contents page. **Fix.** `state.getVars` is wrapped so an unresumable record is never written — nulls dropped, and when `currentpageid` does not resolve, the page on screen (or the most recent page in the history) is substituted. `state.setVars` is wrapped so records written by earlier builds are healed on read, and `state.initTracking` is wrapped so an unforeseen bad record can only cost the resume point, never the whole course. ## 2. Inconsistent saved-progress data The blank resume point is the same root cause as above. **The reported "43 entries against 45 pages" is correct, not a mismatch.** `nrpages` is `x_pageInfo.length` = 44 content pages **+ 1** for the contents page Xerte splices in at `x_pages[0]`. `completedPages` is sized from `markedPages`, which excludes that page and the Welcome page (`unmarkForCompletion="true"`, added in #5), giving 43 = `page_nr` 1…43, Welcome through the final quiz. "Course complete" (`page_nr` 44) is deliberately not required. Now documented in `docs/PROJECT_CONTEXT.md` so it does not get "fixed" later. What *is* a real bug: `setVars()` restores `completedPages` verbatim, so a learner resuming into a build with a different number of tracked pages keeps an array of the wrong length — and `getSuccessStatus()` walks that array, so a short one reports completion early and a long one blocks completion forever. It is now resized to `state.toCompletePages.length`, live tracking options (`nrpages`, tracking mode, pass mark, page timeout) win over saved copies, and page indexes that no longer exist are dropped — which also removes a second crash path, since `x_restorePagesViewed()` writes `x_pageInfo[i].viewed` with no bounds check. ## 3. Completion reachability Verified rather than assumed. `test_full_walkthrough_reports_passed` walks all 44 pages, answers all 45 questions and asserts `lesson_status="passed"` with `score.raw=100`; `test_completion_survives_a_resume` does the same across two sessions. For the record, "all pages required" is weaker than it sounds: a page counts as complete when it is *left* after more than 100 ms (`exit()` ignores shorter visits) and all its interactions exist — and a quiz page registers all of its question interactions on load. So visiting a quiz page is enough for completion; answering is what produces the score. The practical risk was never the page count, it was the crash and the stale array above. ## 4. Score not captured `getVars()` persists only the current page's interaction ("SCORM 1.2 only allows for 4kb of suspend data"), and `getdRawScore()` averages the page interactions in memory. So every quiz page score was discarded on resume: theme quizzes on Monday and the final quiz on Tuesday graded as Tuesday alone, and a learner who answers questions without reaching a quiz's results screen (no `XTSetPageScore` until then) reports `score.raw=0` with `cmi.interactions.*` full of answers — the reported combination. **Fix.** Scored pages are persisted compactly as `xtPages` (`[page_nr, score, weighting, nrinteractions, id]`) and restored as page interactions, so `getdRawScore()` sees the earlier quizzes again. Because `scoremode` is `last`, re-taking a quiz still overwrites the remembered score, and no page is counted twice. A size guard keeps the record inside the 4096-character limit by shedding, in order: old page history, history, `pagesViewed`, then `xtPages`. ## Maintainability The script is no longer maintained by hand inside an XML attribute. `source/scorm_progress.js` is the source of truth and `tools/sync_root_script.py` compiles it into `data.xml`/`preview.xml` (`--check` verifies they are in sync; CI and a test both assert it). The compiler also enforces the existing "no `<`, `>`, `&` or `"`" rule that keeps the attribute round-tripping through the XOT editor unescaped. ## Tests `tests/build_scorm_package.sh` exports a package with a real XOT container — the same import/export path as the release workflow — and `tests/test_scorm_tracking.py` drives that package in headless Chromium against a mock SCORM 1.2 LMS. `.github/workflows/test.yml` runs both on every PR. **15/15 pass** on this branch, built from a clean clone in a fresh container. **6 of them fail on `main`**, including a 45-second start-up timeout on the reported record. The suite covers: loading from the corrupt record, terminate on the contents page, out-of-range `pagesViewed`, stale `completedPages` resizing, resume position, the size guard under 5000 history entries, in-session quiz scoring, score retention across a resume, the 75/25 weighting across two sessions, and the two full-walkthrough completion runs. Also confirmed in a real browser (Playwright MCP, headed Chrome) against the affected learner's record: `main` renders a blank page with that TypeError in the console; this branch renders the contents with the learner's viewed pages ticked, and a click through into a quiz reports interactions and a null-free 1098-character record with a valid resume point. ## Upstream The engine bug is unfixed upstream — `thexerteproject/xerteonlinetoolkits` master (`32c009b`) has the identical unguarded code, and there is no issue for it. An issue with a minimal reproduction (verified against a build of this course with the root `script` attribute stripped, so no code of ours is involved) is drafted and ready to raise. If it is ever fixed upstream, the autosave half of this script becomes redundant and harmless; the repair half stays relevant until `getVars()`/`setVars()` are guarded. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01P9uX9kuo8sErHsfBWBtDyL --- _Generated by [Claude Code](https://claude.ai/code/session_01P9uX9kuo8sErHsfBWBtDyL)_ --------- Co-authored-by: Claude <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
1 participant
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.
Results (cmi.core.score.raw, cmi.core.lesson_status, interactions, cmi.suspend_data) were only reported to the LMS when the learner clicked Save Session (or the window unloaded). If the LMS viewer unloaded the SCO without reliably firing onbeforeunload, nothing was reported and the gradebook stayed empty mid-attempt.
Root cause, traced through Xerte's xttracking_scorm1.2.js + xenith.js (content-level, not fixable in the engine files here -- the release workflow builds the engine from the docker-container branch of RichardoC/xerteonlinetoolkits, so engine JS edits do not persist):
Fix (content-level, no engine/vendoring change -- mirrors the unmarkForCompletion workaround pattern):
Changes to source/data.xml + source/preview.xml (identical):
scriptis an official, optional Nottingham root property (wizard data.xwd line 261: "Add JavaScript to this project. The code will run after the project interface has been set up but before any pages have loaded"); xenith.js injects it once globally via $x_head.append('<script>' + x_params.script + '</script>') (line 2269). The script:state, then calls doLMSCommit(). Guarded to be a no-op outside a live SCORM normal session (state.initialised, scormmode === 'normal', trackingmode !== 'none', !state.finished, doLMSCommit + state.getSuccessStatus present) -- so play.php, xAPI, and noop tracking are unaffected.Validated end-to-end through a running XOT (docker-container branch) instance on host port 8088:
Trade-off: the script wraps XTExitPage/XTExitInteraction at runtime, so it depends on those globals existing and on the engine's global
stateobject shape (getSuccessStatus/getRawScore/getMinScore/getMaxScore/ getVars) -- all stable Nottingham engine internals. If the engine is ever patched upstream to commit on exitInteraction, this script becomes redundant (harmless -- persist() would just call doLMSCommit a second time, which is idempotent) and can be dropped. Do not remove or empty the root script attribute without a replacement -- re-introducing the terminate-only commit will silently revert to "results only on Save".Guidance updates:
grep -c 'xPersistProgress'andunmarkForCompletionlines to the verification checklist.Pending (convention 9 -- re-test on LMS): confirm a learner attempt now shows the gradebook updating incrementally (not only on Save), and that a completed attempt still reports lesson_status=passed with a non-zero grade.
Generated with pi 0.80.6 and GLM 5.2