@missing-elements/h5p-embed 0.7.0 → 0.8.0

package/README.md

@@ -30,7 +30,7 @@ a subdomain shares your site's cookies.
 | `--packages <origins>` | Play packages and fetch library bundles only from these origins (the site's own is always allowed). Add `https://cdn.jsdelivr.net` for `libraries=pack` on a site built with `--no-libraries`. Default: any https host |
 | `--ancestors <origins>` | Only these sites may frame the page (`frame-ancestors`, header only). Default: any site |
 | `--default-libraries <sources>` | The `libraries` value for addresses that name none: `pack` or URLs. Checked against `--packages`. Default: none, so exports without libraries are refused unless the address asks |
-| `--no-libraries` | Leave out the 13.7 MB library pack; `libraries=pack` then fetches it from jsDelivr, where allowed |
+| `--no-libraries` | Leave out the library pack, 13.8 MB in `libraries/`, one archive per library, of which a learner's browser fetches only those a package needs; `libraries=pack` then fetches them from jsDelivr, where allowed |
 | `--force` | Write into a non-empty folder, replacing only this tool's files |
 | `-h`, `--help` / `-v`, `--version` | |
 
@@ -65,7 +65,7 @@ The headers themselves, for a host not listed:
 |---|---|
 | every path | `Content-Security-Policy` (the policy the command prints, with `frame-ancestors` from `--ancestors`), `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin` |
 | `/h5p-sw.js` | `Cache-Control: no-cache`, so an update reaches learners on their next visit |
-| `/frame-assets/*`, `/resizer.js`, `/libraries.h5p` | `Cache-Control: public, max-age=3600, stale-while-revalidate=86400` |
+| `/frame-assets/*`, `/resizer.js`, `/libraries/*` | `Cache-Control: public, max-age=3600, stale-while-revalidate=86400` |
 
 To update, run the command again with `--force` and redeploy.
 
@@ -74,7 +74,8 @@ To update, run the command again with `--force` and redeploy.
 | Parameter | Effect |
 |---|---|
 | `src=<url>` | The package, required. Encode `&`, `#`, `+`, `%` and spaces |
-| `libraries=pack`, `<url>` or `none` | Libraries for an export without them; several are tried in order. `pack` is this domain's copy, or jsDelivr's without one; `hub` means `pack`; `none` turns off `--default-libraries` |
+| `libraries=pack`, `<url>` or `none` | Where libraries come from; several are tried in order. `pack` is this domain's copy, or jsDelivr's without one: a package gets the libraries it lacks from it, and those it carries at the pack's newer versions. `hub` means `pack`; `none` turns off `--default-libraries` |
+| `refresh-libraries=off` | Play the libraries a package carries as exported; `pack` then only fills gaps |
 | `frame`, `copyright`, `export`, `icon`, `reporting` | H5P's action bar and its buttons |
 | `fullscreen=off` | No fullscreen button |
 | `preload=auto` | Start fetching media at once |
@@ -112,7 +113,7 @@ Whatever `xapi=` says, the frame also posts to its parent:
 { context: 'h5p-offline-player', action: 'report',
   source,         // { type: 'range-http' | 'chunked' | 'file', size }
   metadata,       // { title, license, licenseVersion, authors, mainLibrary }, from h5p.json; show as text
-  libraryBundle,  // { url, origin, fromCache }, or null
+  libraryBundle,  // { url, origin, fromCache, refreshed? }, or null; refreshed: [{ library, from, to }]
   elapsedMs }
 { context: 'h5p-offline-player', action: 'error', code, message }  // code 'refused', 'no-src' or the load's
 ```
@@ -127,19 +128,21 @@ await buildSite({ out: 'public/player', packages: ['https://cdn.example.org'] })
 `buildSite` takes `out`, `libraries` (default `true`), `packages`, `ancestors`, `defaultLibraries`
 and `force`, as the flags. `@missing-elements/h5p-embed/embed.js` exports `startEmbed()`, the
 page's script, which reads the page's `<h5p-player>`, `#loader` and `#notice` (see
-`site/index.html` and `site/embed.css`). Its options: `librariesPack` (the URL `libraries=pack`
-names), `packages` (allowed origins, `null` for any), `defaultLibraries`, `runtime` (the
+`site/index.html` and `site/embed.css`). Its options: `pack` (the `@missing-elements/h5p-libraries`
+export, which `libraries=pack` then plays from) or `packBase` (the folder of a copy of its
+`parts/`), `packages` (allowed origins, `null` for any), `defaultLibraries`, `runtime` (the
 `@missing-elements/h5p-runtime` export, for a bundled element) and `askInOwnFrame` (default
 `true`; `false` plays a package from another origin as it is when a same-origin page frames it).
+`librariesPack`, the URL of a whole `libraries.h5p`, still works, as a bundle that only fills gaps.
 
 ```js
 import '@missing-elements/h5p-offline-player'
 import { runtime } from '@missing-elements/h5p-runtime'
-import librariesPack from '@missing-elements/h5p-libraries/libraries.h5p?url'
+import { pack } from '@missing-elements/h5p-libraries'
 import '@missing-elements/h5p-embed/embed.css'
 import { startEmbed } from '@missing-elements/h5p-embed/embed.js'
 
-startEmbed({ runtime, librariesPack, defaultLibraries: 'pack' })
+startEmbed({ runtime, pack, defaultLibraries: 'pack' })
 ```
 
 ## Privacy

package/lib/build.mjs

@@ -7,8 +7,9 @@ import { fileURLToPath } from 'node:url'
  * Writes the embed page as a static site: one folder, deployable to any static host, that a site
  * frames from a player domain of its own. Everything comes from installed packages — the element
  * and its workers from the player's `dist/`, the H5P runtime from its own package as
- * `frame-assets/`, the library pack from `@missing-elements/h5p-libraries` — so the versions are
- * the ones this package was published with, and nothing is fetched.
+ * `frame-assets/`, the library pack's parts from `@missing-elements/h5p-libraries` as
+ * `libraries/` — so the versions are the ones this package was published with, and nothing is
+ * fetched.
  */
 
 export class EmbedError extends Error {}
@@ -149,7 +150,7 @@ function headerRules(csp) {
     { path: '/h5p-sw.js', headers: { 'Cache-Control': 'no-cache' } },
     { path: '/frame-assets/*', headers: { 'Cache-Control': revalidate } },
     { path: '/resizer.js', headers: { 'Cache-Control': revalidate } },
-    { path: '/libraries.h5p', headers: { 'Cache-Control': revalidate } }
+    { path: '/libraries/*', headers: { 'Cache-Control': revalidate } }
   ]
 }
 
@@ -255,8 +256,9 @@ function notice({ version, libraries }) {
   frame-assets/     @missing-elements/h5p-runtime, the H5P core runtime: GPL-3.0-only. Its
                     LICENSE.txt and NOTICE.txt say what it is and where its source is; keep them
                     with it.
-${libraries ? `  libraries.h5p     @missing-elements/h5p-libraries, the H5P hub's libraries, each under its
-                    own licence, listed in libraries.txt.
+${libraries ? `  libraries/        @missing-elements/h5p-libraries, the H5P hub's libraries, one archive per
+                    library and index.json, each under its own licence, listed in libraries.txt.
+                    The player downloads only the ones a package needs.
 ` : ''}
 Serve it from a domain that holds nothing else, and frame it:
 
@@ -287,7 +289,7 @@ async function occupied(dir) {
  *
  * @param {object} options
  * @param {string} options.out
- * @param {boolean} [options.libraries] include the library pack, for `libraries=pack` (default true)
+ * @param {boolean} [options.libraries] include the library pack's parts, for `libraries=pack` (default true)
  * @param {string[] | string | null} [options.packages] the only origins packages may come from
  * @param {string[] | string | null} [options.ancestors] the only origins that may frame the page
  * @param {string | null} [options.defaultLibraries] the `libraries` value for addresses that name none
@@ -308,7 +310,7 @@ export async function buildSite({ out, libraries = true, packages = null, ancest
 
   const player = dirname(installed('@missing-elements/h5p-offline-player/dist/h5p-player.js', 'Run `pnpm build` in the workspace, or reinstall this package.'))
   const runtime = dirname(installed('@missing-elements/h5p-runtime/dist/h5p.css', 'Run `pnpm build` in the workspace, or reinstall this package.'))
-  const pack = libraries ? installed('@missing-elements/h5p-libraries/libraries.h5p', 'Reinstall this package, or pass --no-libraries.') : null
+  const pack = libraries ? dirname(installed('@missing-elements/h5p-libraries/parts/index.json', 'Reinstall this package, or pass --no-libraries.')) : null
   const version = (await readFile(join(player, 'VERSION'), 'utf8').catch(() => 'unknown')).trim()
 
   await mkdir(target, { recursive: true })
@@ -316,11 +318,13 @@ export async function buildSite({ out, libraries = true, packages = null, ancest
   for (const name of PLAYER_FILES) await cp(join(player, name), join(target, name))
   await rm(join(target, 'frame-assets'), { recursive: true, force: true })
   await cp(runtime, join(target, 'frame-assets'), { recursive: true })
+  // A site written before the pack was split carried it whole; that file is gone either way.
+  await rm(join(target, 'libraries.h5p'), { force: true })
+  await rm(join(target, 'libraries'), { recursive: true, force: true })
   if (pack) {
-    await cp(pack, join(target, 'libraries.h5p'))
+    await cp(pack, join(target, 'libraries'), { recursive: true })
     await cp(join(dirname(pack), 'libraries.txt'), join(target, 'libraries.txt'))
   } else {
-    await rm(join(target, 'libraries.h5p'), { force: true })
     await rm(join(target, 'libraries.txt'), { force: true })
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@missing-elements/h5p-embed",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Self-hosted H5P embeds: writes the H5P embed page as a static site for a player domain of your own, then any site frames it with an iframe and one script line. No H5P server, no third-party service; optional allowlists for package hosts and embedding sites.",
   "license": "MIT",
   "repository": {
@@ -43,9 +43,9 @@
     "cli"
   ],
   "dependencies": {
-    "@missing-elements/h5p-libraries": "^0.2.0",
-    "@missing-elements/h5p-offline-player": "^0.9.5",
-    "@missing-elements/h5p-runtime": "^0.2.4"
+    "@missing-elements/h5p-libraries": "^0.3.0",
+    "@missing-elements/h5p-runtime": "^0.2.4",
+    "@missing-elements/h5p-offline-player": "^0.10.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",
@@ -55,7 +55,7 @@
     "vitest": "^5.0.3"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "test": "pnpm --filter @missing-elements/h5p-offline-player build && vitest run",

package/site/embed.js

@@ -5,8 +5,8 @@
  * `h5p-embed` was told when it wrote the site, and the demo's `/embed` with the demo's copy of the
  * library pack.
  *
- *   ?src=<package url>[&libraries=pack|<url> …|none][&preload=auto][&xapi=<parent origin>]
- *    [&frame][&copyright][&export][&icon][&reporting][&fullscreen=off]
+ *   ?src=<package url>[&libraries=pack|<url> …|none][&refresh-libraries=off][&preload=auto]
+ *    [&xapi=<parent origin>][&frame][&copyright][&export][&icon][&reporting][&fullscreen=off]
  *    [&activity-id=<IRI>][&custom-css=<stylesheet url>][&lang=<language tag>]
  *
  * Upward it speaks H5P's own resizer protocol — the `hello` / `resize` exchange that h5p.org's
@@ -23,8 +23,12 @@ const PACK_CDN_ORIGIN = 'https://cdn.jsdelivr.net'
 
 /**
  * @param {object} [options]
- * @param {string | null} [options.librariesPack] the URL of a copy of `@missing-elements/h5p-libraries`
- *   on this site, which `libraries=pack` names; without one, `pack` is the element's copy on jsDelivr
+ * @param {string | null} [options.packBase] the folder of this site's copy of the library pack's
+ *   parts (`parts/` of `@missing-elements/h5p-libraries`), which `libraries=pack` plays from
+ * @param {{ libraries: object[] } | null} [options.pack] the same, as the `pack` export a bundler
+ *   resolves; it wins over `packBase`. Without either, `pack` is the element's copy on jsDelivr
+ * @param {string | null} [options.librariesPack] the URL of a whole `libraries.h5p` on this site,
+ *   for a page written before the pack was split: played as any bundle, with no refresh
  * @param {string[] | null} [options.packages] the origins packages and library bundles may come
  *   from, besides this page's own; `null` plays any, one from another origin `untrusted` when the
  *   storage is this origin's
@@ -38,11 +42,15 @@ const PACK_CDN_ORIGIN = 'https://cdn.jsdelivr.net'
  *   page of its own origin, whose storage it shares. A site whose own preview frames the page for
  *   a package the visitor just chose passes `false`
  */
-export function startEmbed({ librariesPack = null, packages = null, defaultLibraries = null, runtime = null, askInOwnFrame = true } = {}) {
+export function startEmbed({ packBase = null, pack = null, librariesPack = null, packages = null, defaultLibraries = null, runtime = null, askInOwnFrame = true } = {}) {
   const params = new URLSearchParams(location.search)
   const player = document.querySelector('h5p-player')
-  // Before `src`: the element resolves the runtime's files when a package is set.
+  // Before `src`: the element resolves the runtime's files, and reads where the pack is, when a
+  // package is set.
   if (runtime) player.runtime = runtime
+  if (pack) player.pack = pack
+  else if (packBase) player.setAttribute('pack-base', packBase)
+  const ownPack = Boolean(pack || packBase)
   const notice = document.querySelector('#notice')
   const loader = document.querySelector('#loader')
   const framed = window.parent !== window
@@ -237,12 +245,13 @@ export function startEmbed({ librariesPack = null, packages = null, defaultLibra
     if (value === 'none') return { value: '' }
     for (const token of value.split(/\s+/).filter(Boolean)) {
       if (token === 'pack' || token === 'hub') {
-        // This site's copy of the pack; without one, the element's own `pack`, the copy on
-        // jsDelivr, where that may be reached, so a snippet written for `pack` keeps playing after
-        // a rebuild with --no-libraries. `hub` has meant `pack` since player 0.6: the one H5P hub
-        // host that answers a browser serves a catalogue older than current exports need.
-        if (librariesPack) sources.push(librariesPack)
-        else if (permitted(PACK_CDN_ORIGIN)) sources.push('pack')
+        // This site's copy of the pack, which the element was pointed at above; without one, the
+        // element's own `pack`, the copy on jsDelivr, where that may be reached, so a snippet
+        // written for `pack` keeps playing after a rebuild with --no-libraries. `hub` has meant
+        // `pack` since player 0.6: the one H5P hub host that answers a browser serves a
+        // catalogue older than current exports need.
+        if (ownPack || (!librariesPack && permitted(PACK_CDN_ORIGIN))) sources.push('pack')
+        else if (librariesPack) sources.push(librariesPack)
         else return { error: 'This player was set up without the library pack, so libraries=pack is not available here.' }
       } else {
         const origin = urlOrigin(token)
@@ -256,7 +265,8 @@ export function startEmbed({ librariesPack = null, packages = null, defaultLibra
   /**
    * The element's display options, by their attribute names, for the embedding page to ask for:
    * `&frame&copyright&export` shows H5P's action bar with those buttons, `&fullscreen=off` takes
-   * that one away, `&activity-id=` names the statements' object and `&custom-css=` restyles the
+   * that one away, `&refresh-libraries=off` plays a package's own libraries even where the pack
+   * has newer ones, `&activity-id=` names the statements' object and `&custom-css=` restyles the
    * content to the embedding site's taste. `&lang=` is the embedding page's language, which this
    * page cannot read across origins: H5P's own buttons and dialogs follow it. Not `custom-js`,
    * `embed-code` or `user`: a script is a capability on this origin that a link should not hand
@@ -267,6 +277,9 @@ export function startEmbed({ librariesPack = null, packages = null, defaultLibra
       if (params.has(name) && params.get(name) !== 'off') player.setAttribute(name, '')
     }
     if (params.get('fullscreen') === 'off') player.setAttribute('fullscreen', 'off')
+    // The pack's newer versions of the libraries a package carries, unless the embedding page
+    // needs the package exactly as exported.
+    if (params.get('refresh-libraries') === 'off') player.setAttribute('refresh-libraries', 'off')
     for (const name of ['activity-id', 'custom-css']) {
       const value = params.get(name)?.trim()
       if (value) player.setAttribute(name, value)
@@ -358,11 +371,11 @@ export function startEmbed({ librariesPack = null, packages = null, defaultLibra
   // as the host's own: an untrusted package plays with this site's sources alone, the page's
   // default or its pack, and the address's only once the click has trusted it.
   const own = defaultLibraries?.trim() ? librarySources(defaultLibraries.trim()).value : ''
-  const pack = own || librarySources('pack').value
-  if (!pack) {
+  const sitesSources = own || librarySources('pack').value
+  if (!sitesSources) {
     askToTrust()
     return
   }
   player.untrusted = true
-  start(src, pack)
+  start(src, sitesSources)
 }

package/site/main.js

@@ -1,11 +1,11 @@
 /*! @missing-elements/h5p-embed. MIT. */
 // The page's entry: `config.js` is what `h5p-embed` was told when it wrote this site — whether
-// the library pack is here, and which hosts packages may come from.
+// the library pack's parts are here, and which hosts packages may come from.
 import config from './config.js'
 import { startEmbed } from './embed.js'
 
 startEmbed({
-  librariesPack: config.libraries ? new URL('./libraries.h5p', import.meta.url).href : null,
+  packBase: config.libraries ? new URL('./libraries/', import.meta.url).href : null,
   packages: config.packages,
   defaultLibraries: config.defaultLibraries
 })