Skip to content

Play content made for a newer library minor than any source has, on the newest older one (#85) - #86

Merged
alekswebnet merged 2 commits into
mainfrom
feat/downgrade-libraries
Oct 29, 2026
Merged

alekswebnet merged 2 commits into
mainfrom
feat/downgrade-libraries

Conversation

@alekswebnet

@alekswebnet alekswebnet commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Closes #85.

Content made on h5p.com right after a library's minor bump names a version the library pack does not have yet, since the pack follows the hub and the hub follows h5p.com by weeks. Until now the player refused such a package, or, when the newer version was a sub-content library, booted it and crashed with "Cannot read properties of undefined (reading 'on')" and no library named. Now it plays the content at the newest older minor of the same major that a source has, and says so.

What changes

  • The element. downgrade-libraries, on by default; off refuses as before. The element tries every source in libraries for the version named, exactly as today, and only when the last one leaves something missing does it switch the load to the older minor and index once more. So libraries="/bundle.h5p pack" never plays the bundle's older version where the pack has the one named. downgradedLibraries, on the element and in the ready detail, lists each library played older, { library, from, to }, and the console warns. It is the load's, not the bundle's: the older copy may be the package's own, with no bundle attached, as for h5p.org's Impressive Presentation, whose libraries ask for Font Awesome 4.5 beside the 4.3 it carries.
  • The worker. resolveLibraryFolder takes downgrade: with it, a dependency nothing satisfies is served by the newest older minor of the same major, never across a major. The switch is kept in the load's settings (LoadSettings.downgrade, set by an attach-libraries), so a worker started again serves the folders the frame booted with. A reader of an archive still downloading ignores it, since the package may still be bringing its own copy. The planner supplies the pack's older part when the load asks, unless the package carries, or a source provides, one at least as new. The deep index's walk reports what was served older, and now starts from the sub-content content.json names as well as from the manifest, wherever a source has that library's major (an attached archive, or the pack on offer). A stripped export's h5p.json names only its main library, so a question newer than the pack was never seen as missing: the frame booted without its library and died creating it. A library no source has at its major plays as before, so an old export's retired question type is not refused for it.
  • The runtime needs nothing: the content upgrade runs only upward, so the parameters play as written.
  • The verifier. Each downgraded library is a warning and report.downgraded; --no-downgrade-libraries fails the package instead, for the check and the preview.
  • The embed page passes &downgrade-libraries=off through, and its report to the embedding page carries downgradedLibraries.
  • The VS Code extension's bar says how many libraries played older than the content, and which in its tooltip, as it does for the pack's newer versions.
  • The demo's player page has an Older if needed switch beside Newest libraries, says in the status line how many libraries played older, and shows a warning naming them.
  • Docs: the attribute and downgradedLibraries in the API page, a section in the libraries guide, the untrusted guide's table and refusals, a troubleshooting row, the compatibility page's pack paragraph, the verifier's README and guide, the embed README's table, and AGENTS.md.

What it cannot fix

A minor that changed the shape of the content's parameters. H5P marks such a bump with an upgrade step: of the 469 minor bumps in the history of the pack's libraries, 119 have one, 25%, counted from every part's upgrades.js. There the older code does not find what moved, and a part can be missing or drawn wrong. Played untrusted, the content is still checked against the older version's semantics.

Testing

Suite Result
Player unit 358 passed, 11 new: the resolver, findMissingLibraries, the planner's downgrade, and the walk from the parameters
Player browser, Chromium 203 passed, 8 new: a package whose h5p.json names a newer minor than the folder it carries plays its own older copy with no bundle attached, reported in downgradedLibraries and the ready detail, on a host with Range and on one without, and is refused when off; content written for 1.3 with sub-content at 1.2 plays on the pack's 1.2 and 1.1 and reports both; refused with downgrade-libraries="off"; content at the pack's 1.2 whose sub-content alone is at 1.2 plays it on the pack's 1.1, and is refused naming it when off (both fail without the walk from the parameters); a bundle at 1.0 before the pack at 1.2 plays 1.2, nothing downgraded; an untrusted package carrying 1.3 plays on the bundle's 1.0; and the refusal with carried now runs with downgrade-libraries="off"
Verifier 26 passed, 2 new: untrusted, a package made for Question Set 1.99 passes on the pack's 1.21 with a warning and report.downgraded; trusted with no library source, a package naming Question Set 1.99 beside the 1.21 it carries passes with the same warning; the refusal with carried now runs with downgradeLibraries: false
Embed 47 passed, 1 new: a package from elsewhere made for Question Set 1.99 plays untrusted on the pack's 1.21 with no question; the test of the question before its own code now passes &downgrade-libraries=off
VS Code extension, Node 21 passed, 1 new: the bar's count and tooltip; the page passes the list up
Demo app 28 passed
Skills 37 passed
Typecheck, every package clean

pnpm test passed in full on the final tree. An earlier full run lost Vitest's browser connection once, in resume.test.ts, which then passed 10 of 10 alone; it did not happen again.

On the demo's player page, by hand

Two packages made from the demo's quiz with H5P.MultiChoice relabelled 1.17, one more minor than the pack's 1.16, played on the dev server in Chrome:

Package Mode Older if needed Result
Content-only export (the formulas quiz) Trusted on Plays: both questions drawn, 13 formulas typeset, no errors. Status line "one library older than the content", warning "H5P.MultiChoice 1.17 at 1.16.27"
Content-only export Trusted off Refused: "This package needs H5P.MultiChoice-1.17, which neither it nor this site's library pack has"
Full export carrying MultiChoice 1.17 Untrusted on Plays at 1.16.27, with the same warning
Full export carrying MultiChoice 1.17 Trusted on Plays its own 1.17, nothing older

The first row is the one reported, which died with "Cannot read properties of undefined (reading 'on')". The first cut of this branch still failed it, since the main library was the pack's own version and the question's library was named only in content.json; the walk from the parameters is what fixed it.

Not run locally: Firefox and WebKit, which CI's engines job covers.

Not in this change

  • The SCORM writer stays strict: such a package is refused when the zip is written, as before.
  • A sub-content library that no source has at any minor of its major still boots and fails at runtime, unnamed, when played trusted. Played untrusted, the content check removes it, as before.
  • The h5p-verify skill names the new warning and flag only once the verifier is on npm, since skills are installed from main.

Release

A minor for the player, with the new default listed first in the notes, since content refused before now plays: the compatibility page covers the element's attributes, and this plays more than it did rather than less. A minor for the verifier (a new flag and report field) and for the embed package (a new query parameter).

🤖 Generated with Claude Code

alekswebnet and others added 2 commits October 29, 2026 13:16
…, on the newest older one (#85)

h5p.com gets a library's new minor weeks before the hub serves it, and the pack follows the hub,
so content made there can name a version no source has. Such a package was refused, or, when a
question inside it was the newer one, booted without that question's library and died with
"Cannot read properties of undefined (reading 'on')".

The element now tries every source for the version named, as before, and only then switches the
load to the newest older minor of the same major, never across one: `downgrade-libraries`, on by
default, `off` to refuse as before. The switch is kept with the load's settings, and a reader of
an archive still arriving ignores it. The deep index's walk also starts from the sub-content
`content.json` names, wherever a source has that library's major, so a newer question is missing
there and gets the older minor; a library no source has at its major plays as before.

`libraryBundle.downgraded` and a console warning name each library played older. The verifier
warns and reports them (`--no-downgrade-libraries` refuses), the embed page passes
`&downgrade-libraries=off` through, and the demo's player page has an Older if needed switch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ndle (#85)

Found reviewing the first commit. A package served from its own older copy, with no library
source attached, played with only the console saying so: the list rode on `libraryBundle`, which
is null there, so the verifier passed such a package with no warning where it had failed before.
h5p.org's Impressive Presentation is one, its libraries asking for Font Awesome 4.5 beside the
4.3 it carries; an export whose `h5p.json` names a newer minor than its folder is another. The
list is now the load's: `downgradedLibraries`, on the element and in the `ready` detail, which the
verifier, the demo page and the embed page's report read.

Also: the VS Code extension's bar counts the libraries played older, as it counts refreshed
ones; the untrusted guide no longer says a newer minor is refused; and the element reads
`downgrade-libraries` once per index, as it reads `refresh-libraries`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@alekswebnet
alekswebnet merged commit 4d9eec1 into main Oct 29, 2026
9 checks passed
@alekswebnet
alekswebnet deleted the feat/downgrade-libraries branch October 30, 2026 23:03
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.

Play content made for a newer library minor than any source has, on the newest older minor

1 participant