Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 61 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -804,7 +804,9 @@ element, and the element acts. That relay is why `frame-document.ts` has a `mess
Embed adds a separate origin on top.
`tests/browser/untrusted.test.ts` plays `untrusted.h5p`, whose own copy of the fixture content
type marks the frame, against the bundle and then trusted, checks each content type and the
header, injects scripts, reads the policy, and refuses `untrusted-newer.h5p` with `carried`. It
header, injects scripts, reads the policy, plays `untrusted-newer.h5p` on the bundle's older
minor (see *Content written for a newer minor than any source has*) and, with
`downgrade-libraries="off"`, refuses it with `carried`. It
plays `untrusted-markup.h5p`, a form, a script, a handler, a `javascript:` link and a field the
semantics do not name, at the top and in sub-content, through the fixture content type's
`.html()`, untrusted and trusted, and refuses it against `libraries-without-semantics.h5p`; the
Expand Down Expand Up @@ -1206,6 +1208,59 @@ element, and the element acts. That relay is why `frame-document.ts` has a `mess
the demo's bundled page), or the element's `pack` on a site built with `--no-libraries` where
jsDelivr is allowed. A source that fails outright is passed over while another remains; only
the last one's failure is the load's.
- **Content written for a newer minor than any source has plays at the newest older one**
(2026-10-29, #85). H5P Group's October release put library minors on h5p.com weeks before the
hub served them, and the pack follows the hub, so content made there can name a version nothing
here has. Measured that day with the demo's quiz relabelled: a content-only export was refused
naming its main library; one whose sub-content was newer booted and died with "Cannot read
properties of undefined (reading 'on')", nothing drawn and no library named, since nothing checks
sub-content before the boot; an untrusted export carrying its own newer copy was refused with
`carried`. The owner's rule: what can play, plays. So `resolveLibraryFolder` takes `downgrade`,
and with it a dependency nothing satisfies is served from the newest older minor of the same
major, never across a major. Four choices in it. **Strict first**: `index()` in the element tries
every source for the version named, as before, and only when the last leaves something missing
does it switch the load, with an `attach-libraries` carrying `downgrade: true`, and index again,
offering the pack with `downgrade` so that `planPack` supplies its older part (unless the package
carries, or a source provides, one at least as new). So a later source with the version named
wins over an earlier one with an older version, which `pack.test.ts` holds with a bundle at 1.0
before the pack at 1.2. **Kept with the load**: the switch is `LoadSettings.downgrade`, so a
worker started again serves the folders the frame booted with; the next load starts strict.
**Never while arriving**: a partial reader ignores it (`downgrades`), since a package on a host
without `Range` may still be bringing its own copy, and a frame booted early on the older one
would keep it. **From the parameters too**: the deep index's walk (`checkDependencies`) 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 its main library alone and the merged manifest drops what nothing answers for, so the
first cut, which walked the manifest only, never saw a question newer than the pack. It played
the main library and left the question's library unloaded: the demo's formulas quiz with
MultiChoice 1.17 still died as above, which the player page's check by hand found. Missing there
now, it goes to the next source and then to the older minor; `newer-child.h5p` in
`pack.test.ts` is that shape. A library no source has at its major still plays as before,
dropped from the manifest, its sub-content removed by the content check when untrusted, so an
old export's retired question type is not refused for it. The walk names each dependency
served from a versioned folder below the minor asked. The element keeps them as the load's
`downgradedLibraries`, in the `ready` detail too, and warns in the console; the verifier makes
each a warning and `report.downgraded` (`--no-downgrade-libraries` refuses instead), the
player page and the VS Code extension's bar show them, the player page with an Older if needed
switch, and the embed page passes `&downgrade-libraries=off` through and posts the list in its
report. The list is the load's because the older copy may be the package's own, with no bundle
attached: an export whose `h5p.json` names a newer minor than its folder, or h5p.org's
Impressive Presentation, whose libraries ask for Font Awesome 4.5 beside the 4.3 it carries.
The first cut put it on `libraryBundle`, which is `null` there, so only the console said so,
and the verifier passed such a package without a warning where it had failed before; the
branch's own review found it. One thing follows for the
pages that ask before a package's own code runs: untrusted, a package carrying a newer minor than
the pack's now plays on the pack's, so they ask only for a library no source has at its major, or
with the switch off. The embed's `site.test.ts` plays its Question Set 1.99 package both ways.
The runtime needed nothing: the content upgrade runs steps only upward (`isUpgrade`), so the
parameters play as written, the main library is named at the version served, and a
sub-content's string keeps the version it names, which the worker answers from the older folder.
What it costs, counted over the pack the same day: 119 of the 469 minor bumps in its libraries'
history came with an upgrade step, a change of shape the older code does not read; the others
only add. Not done: the SCORM writer stays strict, refusing such a package when the zip is
written; and a sub-content library no source has at any minor of its major still fails at
runtime, unnamed, when played trusted. `downgrade-libraries="off"` refuses as before, and now
names a newer question's library too, where it booted without it.
- **The element says what it is playing: `source`, `metadata`, `libraryBundle`.** Added on
2026-10-09 for the package check an embedding site shows under its preview: the probe's classification and
size (`currentSource`, exposed as a copy), the manifest's metadata plus `mainLibrary` (new on
Expand Down Expand Up @@ -2043,8 +2098,9 @@ ours runs a server.
for a part the zip lacks. What neither the package nor the pack supplies is refused when the zip
is written, by the walk the player makes (`servingFolder` mirrors `reachableFolder`, the walk
`missingDependencies`), run over the package without the folders a part replaces and over the
parts. The walk starts from the sub-content the parameters name as well, which the player would
find missing only when the runtime reached it. So a gap shows up when the teacher writes the zip,
parts. The walk starts from the sub-content the parameters name as well, which the player found
missing only when the runtime reached it until #85, and since then finds at index only where a
source has the library's major. So a gap shows up when the teacher writes the zip,
not when a learner opens it. Measured: the demo's formulas quiz, a stripped export, took 11 parts,
4 MB, 2.8 MB of it MathDisplay; its full exports took none. In Moodle 4.5 the formulas zip
reached `ready`, fetched exactly those 11 parts and the index, and typeset its LaTeX.
Expand Down Expand Up @@ -3094,6 +3150,8 @@ deliberate additions to it, not drift:
at all (`hub` meant the pack until it went before 1.0). Since 0.10 the pack is split, a package downloads only
the parts it needs, and the pack's newer versions play in place of the older ones a package
carries: the design plays what a package carries.
- Content written for a newer minor than any source has plays at the newest older one, once every
source has been tried. The design refuses what is not reachable.
- Content written for an older minor than the one served is upgraded in the frame with the
libraries' own steps. The design serves what a package carries; a bundle that serves newer
minors needs the step the platforms take when they install one.
Expand Down
49 changes: 40 additions & 9 deletions apps/demo/demo/player-page.js
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ const bar = document.querySelector('#progress')
const message = document.querySelector('#message')
const log = document.querySelector('#log')
const refreshToggle = document.querySelector('#refresh')
const downgradeToggle = document.querySelector('#downgrade')
const confirmBox = document.querySelector('#confirm-src')
const modeNote = document.querySelector('#mode-note')
const modeTag = document.querySelector('#mode-tag')
Expand Down Expand Up @@ -119,15 +120,29 @@ player.addEventListener('progress', (event) => {
player.addEventListener('ready', () => {
bar.hidden = true
const refreshed = player.libraryBundle?.refreshed ?? []
modeTag.textContent = player.untrusted
? "Untrusted · libraries from this site's pack · content checked"
: refreshed.length > 0
? `Trusted · ${refreshed.length === 1 ? 'one library' : `${refreshed.length} libraries`} at the pack's newer version`
: player.libraryBundle
? "Trusted · its own libraries, the rest from this site's pack"
: 'Trusted · its own libraries'
const downgraded = player.downgradedLibraries
const libraries = (count) => (count === 1 ? 'one library' : `${count} libraries`)
modeTag.textContent =
(player.untrusted
? "Untrusted · libraries from this site's pack · content checked"
: refreshed.length > 0
? `Trusted · ${libraries(refreshed.length)} at the pack's newer version`
: player.libraryBundle
? "Trusted · its own libraries, the rest from this site's pack"
: 'Trusted · its own libraries') + (downgraded.length > 0 ? ` · ${libraries(downgraded.length)} older than the content` : '')
write(`mode ${modeTag.textContent}`)
for (const { library, from, to } of refreshed) write(`refreshed ${library} ${from} → ${to}`)
for (const { library, from, to } of downgraded) write(`older ${library} ${to}, made for ${from}`)
// Made for a version this site's pack has not got yet, and played at its older one: most of the
// time all of it works, but what the newer version added is not there, so the visitor is told.
if (downgraded.length > 0) {
show(
"Made for newer library versions than this site's pack has, so it plays at older ones: " +
`${downgraded.map(({ library, from, to }) => `${library} ${from} at ${to}`).join(', ')}. ` +
'What the newer versions added is left out. Turn off Older if needed to refuse such packages instead.',
'warning'
)
}
// The build every statement will name in `context.revision`. On a host without Range the frame
// can boot before the index that yields it, and the statements wait for it instead.
if (player.revision) write(`revision ${player.revision}`)
Expand Down Expand Up @@ -241,10 +256,15 @@ const REFRESH_NOTES = {
on: ' Where the pack has a newer version of a library the package carries, that version plays.',
off: ' The libraries the package carries play as exported.'
}
const DOWNGRADE_NOTES = {
on: ' Content made for a newer version than anything here has plays at the newest older one, without what the newer version added.',
off: ' Content made for a newer version than anything here has is refused.'
}
const playsUntrusted = () => form.elements.mode.value === 'untrusted'
const describeMode = () => {
const mode = form.elements.mode.value
modeNote.textContent = NOTES[mode] + (mode === 'trusted' ? REFRESH_NOTES[refreshToggle.checked ? 'on' : 'off'] : '')
modeNote.textContent =
NOTES[mode] + (mode === 'trusted' ? REFRESH_NOTES[refreshToggle.checked ? 'on' : 'off'] : '') + DOWNGRADE_NOTES[downgradeToggle.checked ? 'on' : 'off']
// Untrusted, none of the package's own libraries play, so there is nothing to refresh.
refreshToggle.disabled = mode === 'untrusted'
}
Expand All @@ -259,7 +279,12 @@ const applyMode = () => {
player.untrusted = untrusted
if (refreshToggle.checked) player.removeAttribute('refresh-libraries')
else player.setAttribute('refresh-libraries', 'off')
return untrusted ? ' (untrusted: none of its own code runs)' : refreshToggle.checked ? '' : ' (libraries as exported)'
if (downgradeToggle.checked) player.removeAttribute('downgrade-libraries')
else player.setAttribute('downgrade-libraries', 'off')
return (
(untrusted ? ' (untrusted: none of its own code runs)' : refreshToggle.checked ? '' : ' (libraries as exported)') +
(downgradeToggle.checked ? '' : ' (no older versions)')
)
}

/** Plays a package at a URL, in the switch's mode. */
Expand Down Expand Up @@ -322,6 +347,12 @@ refreshToggle.addEventListener('change', () => {
reload?.()
})

// And content made for a newer version than the pack has: played at its older one, or refused.
downgradeToggle.addEventListener('change', () => {
describeMode()
reload?.()
})

// A sample marked `data-untrusted` plays as data against this site's bundle: a content-only
// export, as h5p.com and h5p.org make them, the way a site plays a package it did not make. The
// others play in whichever mode the switch is in.
Expand Down
10 changes: 7 additions & 3 deletions apps/demo/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -114,9 +114,10 @@ <h1>Self-hosted H5P in one web component</h1>
Choose file
<input type="file" id="file" accept=".h5p,application/zip" />
</label>
<!-- The element's two modes, for whatever the visitor plays next, and whether a library the
package carries plays at the pack's newer version: changing either plays the current
package again. See demo/player-page.js. -->
<!-- The element's two modes, for whatever the visitor plays next; whether a library the
package carries plays at the pack's newer version; and whether content made for a
newer version than the pack has plays at its older one: changing any of them plays
the current package again. See demo/player-page.js. -->
<div class="mode-row">
<div class="mode" role="radiogroup" aria-label="How to play the package" aria-describedby="mode-note">
<label><input type="radio" name="mode" value="trusted" checked />Trusted</label>
Expand All @@ -125,6 +126,9 @@ <h1>Self-hosted H5P in one web component</h1>
<div class="mode">
<label><input type="checkbox" id="refresh" checked aria-describedby="mode-note" />Newest libraries</label>
</div>
<div class="mode">
<label><input type="checkbox" id="downgrade" checked aria-describedby="mode-note" />Older if needed</label>
</div>
<p class="mode-note" id="mode-note">
The package's own scripts run on this site. What it lacks comes from this site's library pack.
</p>
Expand Down
4 changes: 3 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ meaning, and a new error `code` or `progress` phase can only be added.
| `pack-base` | attribute | Where `pack` is: the folder of a copy of `@missing-elements/h5p-libraries`' `parts/` on your site. Default: jsDelivr, at the version this release pins |
| `pack` | property | The `pack` export of `@missing-elements/h5p-libraries`, as a bundler emits it; wins over `pack-base`. Set before `src` |
| `refresh-libraries` | attribute | `off` plays the libraries a package carries as exported, and `pack` only fills gaps. Default: the pack's newer versions play |
| `downgrade-libraries` | attribute | `off` refuses content made for a newer minor version of a library than any source has. Default: once every source has been tried for that version, the newest older minor of the same major plays it, reported in `downgradedLibraries` and the console |
| `untrusted` | attribute, property | Plays a package you did not make as data: its own library folders are ignored and the libraries come from `libraries` (default `pack`), `content/` serves only H5P's own file types, and the frame's script policy names exact paths. Its content is checked against each library's `semantics.json`, as the H5P CMS plugins check it. A package that needs its own copy of a library is refused, with `missingLibraries.carried` set |
| `allow-origins` | attribute | Extra origins for the frame's CSP, space separated |
| `frame`, `copyright`, `export`, `icon`, `embed` | attribute | Show the H5P action bar and its buttons. `export` needs `download-url` or a package URL, `embed` needs `embed-code` |
Expand All @@ -38,6 +39,7 @@ meaning, and a new error `code` or `progress` phase can only be added.
| `source` | read-only | `{ type: 'range-http' \| 'chunked' \| 'file', size, … }` |
| `metadata` | read-only | `h5p.json`'s metadata plus `mainLibrary` |
| `libraryBundle` | read-only | `{ url, origin, fromCache, refreshed? }` for what supplied libraries: for the pack, `refreshed` lists the libraries the package carries that played at the pack's version, `{ library, from, to }` |
| `downgradedLibraries` | read-only | The libraries the content names at a newer minor than any source has, which played at the newest older one (`downgrade-libraries`): `{ library, from, to }`, with `from` the version named, such as `1.17`, and `to` the one played, such as `1.16.27`. Empty when none did. The older version may be the package's own, with no `libraryBundle` |
| `scope` | read-only | The Service Worker scope |

## Methods
Expand All @@ -51,7 +53,7 @@ Events are `CustomEvent`s:

| Event | `detail` | When |
|---|---|---|
| `ready` | `{ pkgId, source, metadata, revision, libraryBundle }` | The content is visible |
| `ready` | `{ pkgId, source, metadata, revision, libraryBundle, downgradedLibraries }` | The content is visible |
| `xapi` | `{ statement, verb }` | Any xAPI statement; nothing is stored |
| `finished` | `{ statement }` | The content reported its result: a `completed` or `answered` statement from the content itself, not from a part inside it. That is H5P's own `setFinished` rule, except that a part created without a parent counts as a part too, which H5P's rule misses for Interactive Book's chapters and Game Map's exercises. It can come more than once, for a question checked again; the last is the result. Content that reports no result of its own never raises it, and Interactive Book reports one only with `reporting` |
| `userdata` | `{ pkgId, dataType, subContentId, data, revision }` | With `resume`: the content saved its state; `data: null` means delete it |
Expand Down
6 changes: 4 additions & 2 deletions docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,10 @@ always plays a package against the same libraries. The pin moves in a minor rele
patch: with `pack`, a library a package carries plays at the pack's newer version, so a new pack
changes what packages that carry their libraries play, and their `revision`, and a learner's state
saved against the build before starts over. Libraries move to newer minors, and content written
for an older minor is brought up by the libraries' own upgrade steps. A pack that drops a content
type or a library major the one before carried comes only with a player major.
for an older minor is brought up by the libraries' own upgrade steps. Content written for a newer
minor than any source has plays at the newest older one unless `downgrade-libraries="off"`, and
plays at the newer one once a pack has it. A pack that drops a content type or a library major the
one before carried comes only with a player major.

What is covered of the pack itself: the `pack` export, `parts/` with its `index.json` and one
`<folder>.h5p` per library, and `libraries.h5p`, the whole pack as one file.
Expand Down
Loading
Loading