Vendor the H5P core from h5p-php-library and retire h5p-standalone
Merged
AL
1mo ago+8306+8306+0123456789012345678901234567890123456789-375-375-012345678901234567890123456789
Closes #37.
The runtime no longer uses h5p-standalone. It vendors the H5P core from h5p-php-library at a pinned commit, and its boot script loads the core itself, in the order the worker gives.
What changed
The core, vendored (packages/runtime/)
pnpm core:sync [<ref>](scripts/sync-core.mjs) fetches h5p-php-library at a commit intovendor/h5p-core/, which is committed. It is pinned at cb64a1f (2026-08-11, core API 1.28), the commitcontent-check.tsis already ported from.- What it takes, and in what order, is upstream's own list:
H5PCore::$scriptsandH5PCore::$stylesinh5p.classes.phpat that commit. It also takes the fonts and image the stylesheets reach, their licence files, and the player's English strings fromgetLocalization(), ending where the hub's sharing-wizard strings begin. - Those English strings are the same 67 h5p-standalone carried, word for word, so
l10n-rules.mjsreads them fromstrings.jsonand no language file changes. frame.bundle.jsis the ten scripts joined in upstream's order and minified with top-level names kept. They are global scripts, as a site loads them, and H5P'sjQuery.noConflict(true)needs jQuery's global (h5p-standalone built that file as an ES module to get the same effect).- Size: 48.5 kB gzipped, against 54.6 kB for
frame.bundle.jsandmain.bundle.jstogether before. h5p.cssis built as before, from the eight sheets.NOTICE.txtandMANIFEST.jsonnow name the commit, so the corresponding source is exact.- The
h5p-standalonedependency is gone, andmain.bundle.jswith it.
The boot (src/frame-boot.ts)
- The boot script builds
H5PIntegrationitself, field for field as h5p-standalone did, then mounts the.h5p-contentdiv, adds the core's and the libraries' stylesheets and scripts (markeddata-h5p, waited for), and holdsH5P.initback with the core's ownpreventInit. - The upgrade, the content check, the user-data shim and the init sequence are unchanged.
urlis now the package's root rather than a random id. No library in the pack reads it, andgetContentPathwas already answered fromcontentUrl.
What to load: the worker's boot route (packages/player/src/sw/library-load.ts, mount.ts)
…/h5p/boot/<load>answers aLibraryLoad:- the main library at the version served, in full;
- every library's scripts and styles, dependencies first;
libraryDirectoriesfor a library in a folder its version does not name, which the core'sH5P.getLibraryPathreads;- the
upgradeslist.
- Why the frame asks for it instead of the worker writing it into the frame document: only a request from the frame can reopen a picked file's reader after a worker restart. The page is asked for the file through the frame, which doesn't exist yet while its own document is being served.
- The order is h5p-standalone's to the letter: its
loadDependencieslevels, itssortDependenciesedges, andtoposort2.0.2 with its tie-breaks, including the phantom node a library without dependencies gets. Two deliberate differences:- A library is named by the folder that serves it, so one folder answering two requested versions loads once.
- A dependency cycle is broken where it closes; h5p-standalone threw on one.
- A library nothing provides makes the route refuse the load, naming the library.
Across versions
- A record that names
mainJscame from an element paired with runtime ≤ 0.2. For it, the worker still writes the old document: the loader script, and the upgrade list in the config. - Checked by hand: runtime 0.2.5 from npm, handed over through the
runtimeproperty, plays against this worker. - The new boot script, given a document from an older worker (no
bootURL), fails with a message to update the player andh5p-sw.jstogether.
Testing
- Same order as before:
- The new
tests/unit/library-load.test.tsruns h5p-standalone's ownloadDependencies,sortDependenciesandtoposortbeside the port on 500 random dependency graphs. - In the frame, I captured what loads for 68 packages on
mainand on this branch: the six demo packages, nine fixtures and the sweep's 55. All 68 load the same files in the same order. 62 are byte-identical. In the other six, only folder names changed:H5P.Question-1.5/…where h5p-standalone requested1.4/…and the server answered from 1.5.
- The new
- One package that failed now plays:
boardgame.h5p(in the fixtures folder, not built by the repo). Its folders are named without versions. With the pack, the refreshed parts sit in versioned folders beside them, and h5p-standalone named every folder by its first dependency's probe, so it ended on "Unexpected end of JSON input". The new fixtureunversioned-pack.h5pand a test inpack.test.tspin the fix. - Sweep: 110 of 110 plays pass on
mainand on this branch. The reports are identical apart from timings, so every content type sends the same statements in both modes. - Suites:
- Chromium, player: unit 341/341 (incl. the new tests), and 527/527 across all of its projects.
- Firefox
test:engine: 182/182, plus the app's 24 (3 Chromium-only skipped). - WebKit
test:engine: 182/182, plus the app's 24. - Demo app in Chromium: 27/27.
- Embed: 26/26 (its test listed
main.bundle.jsamong a written site's files). - Verify: 15/15. Runtime: 180/180.
pnpm typecheckpasses;pnpm build:demobuilds.
- Verifier: h5p-standalone's own
test/h5p-test.h5ppasses, and so do the demo quiz and video. - One intermittent failure:
stalling-host.test.ts's 35-second outage test failed 4 times in a row with the tail arriving at 26–32 s. That was while Spotlight was indexing a worktree, with load average 20. It then passed 5 times and in the full run once the machine was quiet.mainpassed it twice at the same time, so I can't fully rule out this branch. What fits load is the server giving up after twice the stall bound when the Jobs worker's liveness notices are delayed. Keep an eye on it in CI.
Not covered
- Safari and iOS by hand.
- A runtime ≤ 0.2 through
assets-basewith this player: the element no longer namesmain.bundle.js, so that pairing does not work and is not meant to. - An element from before this change against a stale
h5p-sw.jscopy: the old worker cannot write a document for a runtime withoutmainJs. That is the existing "updateh5p-sw.jswith the element" case.
Release
Runtime and player go together:
- The runtime's
runtimeexport losesmainJsand itsdist/losesmain.bundle.js. - Its boot script needs the
bootroute. - The player's peer range has to move to the new runtime at release (the worker still serves 0.2 records, so it can include
^0.2). - The release notes name the core's commit.
🤖 Generated with Claude Code