Skip to content

Warm and refresh only the libraries a package plays; write the upload-check libraries after the media - #150

Merged
alekswebnet merged 3 commits into
mainfrom
fix/install-libraries-boot
Nov 7, 2026
Merged

alekswebnet merged 3 commits into
mainfrom
fix/install-libraries-boot

Conversation

@alekswebnet

Copy link
Copy Markdown
Contributor

Closes #148.

The libraries #147 added for an H5P site's upload check slowed the start of every package that carries them. Over a host that honours Range, the player's warm pulled them before the frame booted. Over one that ignores it, the normalizer sorted them before content.json. From a host paced to 1 MB/s, the demo's video was ready at 4.5 s either way, where it took 1.9 s before #147. Platform exports carry the same editor libraries, so they were paying this already, and with the pack they paid again: the plan refreshed every library they carry, the many nothing plays included, before the frame booted.

What changes

  • The warm (PackageReader.warmSpans) now takes only the root, content/ and the library folders h5p.json declares (declaredFolders). An export lists there, flattened, every library its content plays, and none of those that only the upload check wants. In all 88 packages of the local corpus, h5p.json declared every folder the dependency walk reaches, so nothing has to be read to decide. A folder left out is still served on demand if anything asks for it. An h5p.json that declares nothing the archive carries keeps every folder in, as before.
  • The pack's plan (PackageReader.ownLibraries) reads the library.json of each folder the content reaches, starting from h5p.json and the sub-content its parameters name and following each preloadedDependencies. It takes every other folder by its name. Without this, the deep index after the warm would read each editor's library.json with a request of its own. It also stops refreshing libraries nothing plays. A platform's export carries every type its editor can hold, so this was most of what the pack downloaded for one before its frame booted (below). The demo's video no longer downloads H5P.SingleChoiceSet 1.11 (180 kB), and Image Sequencing no longer downloads the pack's H5P.Audio 1.5 to replace its 1.2. ownLibraries in pack-plan.ts takes an optional readable for this; the SCORM writer still reads every folder.
  • h5p-author's Node build and the demo's content script pass these folders to the normalizer as last (Normalizer: write named library folders after the media (last) #149), so in a package with media they come after the media. The demo's quiz, video and glossary are rewritten in that layout, with the same entries, CRCs and sizes. The video's content.json is back at 1.46 MB, from 4.08.
  • Docs: the warm rule in design/serving.md and its line in AGENTS.md, the refresh rule and h5p-author packages carry no H5P editor libraries, so Moodle refuses them on a site that lacks those #146's cost note in design/libraries.md, design/author.md, design/normalize.md (with its long line rewrapped), design/demo.md, and one line in docs/libraries.md for integrators.

Checked

  • Timings from a host paced to 1 MB/s, the player from main against this branch's:

    Package Host main this branch
    Demo video, 5.2 MB, run after the media Range 4.5 s 1.9 s
    Demo video, as on main, run before the content Range 4.6 s 2.0 s
    Demo video before Carry the editor libraries an H5P site's upload check wants, so h5p-author packages install on a fresh Moodle #147, 2.5 MB Range 1.9 s 1.9 s
    Demo video, run after the media no Range 2.3 s 2.4 s
    Course Presentation, a platform's export, 5.5 MB Range 5.8 s 2.2 s
    Interactive Video export, 4.2 MB Range 4.4 s 2.5 s
    The same, 10 MB/s with 100 ms on every request Range 1.6 s 1.4 s
    Column export, 5.4 MB, 10 MB/s with 100 ms on every request Range 2.5 s 1.7 s

    Leaving folders out can split the warm into more requests: the Interactive Video's load went from 5 to 9, the Column export's from 8 to 13. Even with 100 ms added to every request, both were ready sooner. Across the corpus, the warm comes to 149 MB instead of 231.

  • Player: 598 tests (unit and both browser projects), five of them new.

    • warm.test.ts: editor folders between and after the played ones are left out, and an h5p.json that declares nothing keeps every folder.
    • package-reader.test.ts: ownLibraries reads only what the content reaches.
    • range-requests.test.ts: installable.h5p's run is never asked for, with the pack offered and without, and the request count stays at four.

    The new tests fail without the change. The pack case also fails on its own when the plan reads every folder again (five requests).

  • h5p-verify on the regenerated quiz, video and glossary, with their own libraries and against the pack: all pass, with no warnings. With the pack, the video refreshes only H5P.Components.

  • Workspace: pnpm test passes across the workspace (author 142, embed 81, skills 73, verify 27, demo 21, and the rest), and pnpm sweep plays 110 of 110 content types, untrusted and trusted.

  • With libraries="pack", five platform exports from the corpus: the plan downloaded 12.7 MB of parts before the frame booted, where what they play takes 1.9 MB. A Course Presentation refreshed 31 libraries (3.4 MB) and now refreshes 3 (0.33 MB). All five pass h5p-verify either way.

Costs, plainly

  • A package played with libraries="pack" that carries a library nothing plays, at an older version than the pack's, now attaches fewer parts. Its revision changes once, so a learner's saved state starts over with H5P's dialog, as after a pack release. This lands in the player minor that already moves the pin to pack 1.1.0.
  • If a package's h5p.json leaves out a library its content plays, that folder is served on demand over a host with Range: a request or two per file, as before the warm existed. None of the 88 packages did this.
  • The h5p-normalize command still sorts every library folder before content/. If a person normalizes a page-built h5p-author package by hand, its run goes back before content.json. This matters only on a host without Range, since the warm skips the run either way. The command could use the same rule, what h5p.json declares; that is left for later.

Release: this ships in the player minor with pack 1.1.0 (the pin moved in #147). The normalizer's minor comes before h5p-author's, which now passes last; an older normalizer ignores it. Embed and the extension follow with the player.

Over a host that honours Range, the warm pulled every library folder
before the frame booted, the editor libraries an H5P site's upload check
wants included (#146), and the pack's plan then read and refreshed every
one. The warm now takes the folders h5p.json declares, and the plan reads
and refreshes the folders the content reaches; the rest are served on
demand. From a host paced to 1 MB/s the demo's video is ready at 1.9 s
instead of 4.5, a platform's Course Presentation export at 2.2 s instead
of 5.8.

Part of #148.
…r the media

h5p-author's Node build and the demo's content script pass their install
folders to the normalizer as `last` (#149), so in a package with media a
host that ignores Range boots before they arrive too. The demo's quiz,
video and glossary are rewritten in that layout, with the same entries:
the video's content.json is back at 1.46 MB, from 4.08.

Part of #148.
… exports

Measured on five exports from the local corpus with the pack: 12.7 MB of parts before the frame booted, where what they play takes 1.9.

Part of #148.
@alekswebnet alekswebnet self-assigned this Nov 7, 2026
@alekswebnet
alekswebnet merged commit 41a4209 into main Nov 7, 2026
9 checks passed
@alekswebnet
alekswebnet deleted the fix/install-libraries-boot branch November 8, 2026 13:38
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.

Normalizer: an option to write named library folders after the media

1 participant