@missing-elements/h5p-embed 1.2.1 → 1.3.1

package/README.md

@@ -83,6 +83,7 @@ To update, run the command again with `--force` and redeploy.
 | `src=<url>` | The package, required: an `http` or `https` URL, or a path on the player domain. Encode `&`, `#`, `+`, `%` and spaces |
 | `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. `none` turns off `--default-libraries` |
 | `refresh-libraries=off` | Play the libraries a package carries as exported; `pack` then only fills gaps |
+| `downgrade-libraries=off` | Refuse content made for a newer version of a library than any source has, instead of playing it at the newest older one |
 | `frame`, `copyright`, `export`, `icon`, `reporting` | H5P's action bar and its buttons |
 | `fullscreen=off` | No fullscreen button |
 | `preload=auto` | Start fetching media at once |
@@ -162,7 +163,29 @@ complete such an activity on viewing it instead. Replacing the zip with one writ
 belongs to what it was saved in.
 
 Checked in Moodle 4.5: the score reaches the gradebook, and a learner who leaves halfway continues
-there on the next launch. Other LMSs have not been tried yet.
+there on the next launch.
+
+Checked in Frappe LMS too, on its `develop` branch, uploaded as a SCORM chapter. A learner who
+leaves halfway continues there, but Frappe records less than Moodle. It marks the lesson done only
+when the content reports a pass, so a quiz needs a pass mark; a failed attempt, or content that
+reports only `completed`, leaves the lesson open. It keeps no score. Frappe sends a file whole
+rather than in ranges, so the package is downloaded in full when the lesson opens, and a large video
+in it starts once the download has reached it.
+
+Checked in SCORM Cloud too: the score, whether it passed, the time and the learner's place are
+recorded, and an export without its libraries plays from the parts in the zip. A zip written by
+embed 1.3.0 or earlier cannot be imported there ("IO Error processing zip"), nor, likely, into
+other LMSs that read uploads with Java; write it again with a later version.
+
+Checked in ILIAS 11 too, uploaded as a SCORM learning module. The score, whether it passed, the
+time and the learner's place are recorded, but only once Learning Progress is on, which a fresh
+ILIAS has off: without it ILIAS's SCORM player keeps the learner's place and drops every score and
+status the content sends. Turn it on in Administration, then in the module's Learning Progress
+settings choose "Collection of SCORM Items" and tick the item. ILIAS sent the larger packages whole
+rather than in ranges, as Frappe does. With a zip written by embed 1.3.0 or earlier, ILIAS records
+no time for a session the learner ends by closing the tab; write it again with a later version.
+
+Other LMSs have not been tried yet.
 
 ## As a library
 

package/lib/crc32.mjs

@@ -0,0 +1,36 @@
+import zlib from 'node:zlib'
+
+/** @type {Uint32Array | undefined} */
+let table
+
+/**
+ * @param {Uint8Array} bytes
+ * @param {number} previous
+ */
+function tableCrc32(bytes, previous) {
+  if (!table) {
+    table = new Uint32Array(256)
+    for (let n = 0; n < 256; n++) {
+      let c = n
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+      table[n] = c >>> 0
+    }
+  }
+  let crc = ~previous >>> 0
+  for (let i = 0; i < bytes.length; i++) crc = table[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8)
+  return ~crc >>> 0
+}
+
+/**
+ * CRC-32 of `bytes`, continuing from `previous`. Native from Node 22.2 on; a table before that.
+ * A namespace import rather than a named one, because a named import of a builtin's missing
+ * export fails at link time and would take the whole script down on an older Node.
+ *
+ * A copy of the normalizer's `lib/crc32.mjs`; keep the two in step.
+ *
+ * @type {(bytes: Uint8Array, previous?: number) => number}
+ */
+export const crc32 =
+  typeof zlib.crc32 === 'function'
+    ? (bytes, previous = 0) => zlib.crc32(bytes, previous)
+    : (bytes, previous = 0) => tableCrc32(bytes, previous)

package/lib/scorm.mjs

@@ -6,6 +6,7 @@ import { Writable } from 'node:stream'
 import { fileURLToPath } from 'node:url'
 import { BlobReader, TextReader, TextWriter, ZipReader, ZipWriter, configure } from '@zip.js/zip.js'
 import { EmbedError, PLAYER_FILES, installed } from './build.mjs'
+import { crc32 } from './crc32.mjs'
 
 /**
  * Writes a SCORM 1.2 package that plays one `.h5p` in an LMS and reports its result there: the
@@ -382,6 +383,16 @@ function sha256(file) {
   })
 }
 
+/**
+ * A file's CRC-32, read as a stream.
+ * @param {string} file
+ */
+async function fileCrc32(file) {
+  let crc = 0
+  for await (const chunk of createReadStream(file)) crc = crc32(chunk, crc)
+  return crc
+}
+
 /**
  * Every file under a folder, as zip paths relative to it, sorted.
  * @param {string} dir
@@ -533,9 +544,20 @@ export async function buildScorm({ h5p, out, force = false }) {
     const zip = new ZipWriter(Writable.toWeb(createWriteStream(partial)))
     await zip.add('imsmanifest.xml', new TextReader(xml))
     for (const [name, content] of files) {
-      // The package, the pack's parts and the fonts are compressed already.
-      const level = name.endsWith('.h5p') || name.endsWith('.woff2') ? 0 : 6
-      await zip.add(name, 'text' in content ? new TextReader(content.text) : new BlobReader(await openAsBlob(content.file)), { level })
+      if ('text' in content) {
+        await zip.add(name, new TextReader(content.text), { level: 6 })
+        continue
+      }
+      const blob = await openAsBlob(content.file)
+      // The package, the pack's parts and the fonts are compressed already, so they are stored.
+      // Written into a stream, an entry gets a data descriptor, and a Java ZipInputStream refuses
+      // a stored entry that has one: SCORM Cloud refused exactly those (#92). Passed through with
+      // its size and CRC, it gets a complete local header instead, and is still streamed, not held.
+      if (name.endsWith('.h5p') || name.endsWith('.woff2')) {
+        await zip.add(name, new BlobReader(blob), { passThrough: true, compressionMethod: 0, uncompressedSize: blob.size, crc32: await fileCrc32(content.file) })
+      } else {
+        await zip.add(name, new BlobReader(blob), { level: 6 })
+      }
     }
     await zip.close()
     await rename(partial, target)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@missing-elements/h5p-embed",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "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; or wraps one .h5p as a SCORM 1.2 package an LMS plays and grades. No H5P server, no third-party service; optional allowlists for package hosts and embedding sites.",
   "license": "MIT",
   "repository": {
@@ -60,8 +60,8 @@
   "dependencies": {
     "@zip.js/zip.js": "^2.24.0",
     "@missing-elements/h5p-libraries": "^1.0.0",
-    "@missing-elements/h5p-runtime": "^1.0.0",
-    "@missing-elements/h5p-offline-player": "^1.1.2"
+    "@missing-elements/h5p-offline-player": "^1.2.0",
+    "@missing-elements/h5p-runtime": "^1.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",

package/scorm/scorm.js

@@ -151,13 +151,36 @@ player.addEventListener('finished', (event) => {
   commit()
 })
 
-// The session ends with the page. Unfinished, it is suspended, so the next launch resumes it.
+/*
+ * The session ends with the page. Unfinished, it is suspended, so the next launch resumes it.
+ *
+ * Its time and how it ended are committed on `beforeunload` too, while the page is still there,
+ * and the session is finished on `pagehide`, once the page is going for good. ILIAS sends what a
+ * closing page writes with a beacon only during `beforeunload`, `unload` or a click; on `pagehide`
+ * it tries a synchronous request, which Chrome refuses while a page goes, so the finish alone lost
+ * the session's time there (#94). The commit is all `beforeunload` does: the content saves its
+ * state for the last time on its own frame's `beforeunload`, which comes after this page's, and a
+ * learner asked whether to leave may stay.
+ */
 let ended = false
+
+function writeEnd() {
+  set('cmi.core.session_time', timespan(Date.now() - started))
+  set('cmi.core.exit', finished ? '' : 'suspend')
+}
+
+if (initialized) {
+  addEventListener('beforeunload', () => {
+    if (ended) return
+    writeEnd()
+    commit()
+  })
+}
+
 addEventListener('pagehide', () => {
   if (!initialized || ended || !api) return
   ended = true
-  set('cmi.core.session_time', timespan(Date.now() - started))
-  set('cmi.core.exit', finished ? '' : 'suspend')
+  writeEnd()
   api.LMSFinish('')
 })
 

package/site/embed.js

@@ -5,7 +5,7 @@
  * `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][&refresh-libraries=off][&preload=auto]
+ *   ?src=<package url>[&libraries=pack|<url> …|none][&refresh-libraries=off][&downgrade-libraries=off][&preload=auto]
  *    [&xapi=<parent origin>][&frame][&copyright][&export][&icon][&reporting][&fullscreen=off]
  *    [&activity-id=<IRI>][&custom-css=<stylesheet url>][&lang=<language tag>]
  *
@@ -141,20 +141,23 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
    * What the player learnt about the package, for the embedding page to show: whether the host
    * streamed it or made the browser download it whole (`source.type`), how big it is, what it
    * says it is (`metadata`), where libraries it did not carry came from (`libraryBundle`, `null`
-   * when it carried its own), and how long it took here. Posted once, when the content is up:
+   * when it carried its own), which played at an older version than the content names
+   * (`downgradedLibraries`, empty when none did), and how long it took here. Posted once, when the
+   * content is up:
    *
-   *   { context: 'h5p-offline-player', action: 'report', source, metadata, libraryBundle, elapsedMs }
+   *   { context: 'h5p-offline-player', action: 'report', source, metadata, libraryBundle,
+   *     downgradedLibraries, elapsedMs }
    *
    * and to any parent, like the heights: the parent named the package, and the manifest's strings
    * are the package's own to tell. A parent treats them as text. A load that fails before the
    * content is up posts `{ context: 'h5p-offline-player', action: 'error', code, message }`
    * instead, a refusal by this page included (`code: 'refused'`). The shapes are an interface:
-   * a site that checks packages builds its preview from them, so they do not change.
+   * a site that checks packages builds its preview from them, so a field is only ever added.
    */
   let startedAt = 0
 
   player.addEventListener('ready', (event) => {
-    const { source, metadata, libraryBundle } = /** @type {CustomEvent<ReadyDetail>} */ (event).detail
+    const { source, metadata, libraryBundle, downgradedLibraries } = /** @type {CustomEvent<ReadyDetail>} */ (event).detail
     post({
       context: 'h5p-offline-player',
       action: 'report',
@@ -167,6 +170,8 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
         mainLibrary: metadata.mainLibrary
       },
       libraryBundle,
+      // Absent from an element older than the page's own; this page and the element ship together.
+      downgradedLibraries: downgradedLibraries ?? [],
       elapsedMs: Math.round(performance.now() - startedAt)
     })
   })
@@ -311,12 +316,13 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
    * 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, `&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 for a package that
-   * does not name its own language, and follow the content's where it does. Not `custom-js`,
-   * `embed-code` or `user`: a script is a capability on this origin that a link should not hand
-   * out, the embed is the embed, and a learner's name has no place in a URL.
+   * has newer ones, `&downgrade-libraries=off` refuses content made for a newer version of a
+   * library than any source has, `&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
+   * for a package that does not name its own language, and follow the content's where it does.
+   * Not `custom-js`, `embed-code` or `user`: a script is a capability on this origin that a link
+   * should not hand out, the embed is the embed, and a learner's name has no place in a URL.
    */
   const applyOptions = () => {
     for (const name of ['frame', 'copyright', 'export', 'icon', 'reporting']) {
@@ -326,6 +332,9 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
     // 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')
+    // Content made for a newer version than any source has plays at the older one, unless the
+    // embedding page would rather have it refused.
+    if (params.get('downgrade-libraries') === 'off') player.setAttribute('downgrade-libraries', 'off')
     for (const name of ['activity-id', 'custom-css']) {
       const value = params.get(name)?.trim()
       if (value) player.setAttribute(name, value)

package/types/lib/crc32.d.mts

@@ -0,0 +1,10 @@
+/**
+ * CRC-32 of `bytes`, continuing from `previous`. Native from Node 22.2 on; a table before that.
+ * A namespace import rather than a named one, because a named import of a builtin's missing
+ * export fails at link time and would take the whole script down on an older Node.
+ *
+ * A copy of the normalizer's `lib/crc32.mjs`; keep the two in step.
+ *
+ * @type {(bytes: Uint8Array, previous?: number) => number}
+ */
+export declare const crc32: (bytes: Uint8Array, previous?: number) => number;

package/types/site/embed.d.ts

@@ -5,7 +5,7 @@
  * `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][&refresh-libraries=off][&preload=auto]
+ *   ?src=<package url>[&libraries=pack|<url> …|none][&refresh-libraries=off][&downgrade-libraries=off][&preload=auto]
  *    [&xapi=<parent origin>][&frame][&copyright][&export][&icon][&reporting][&fullscreen=off]
  *    [&activity-id=<IRI>][&custom-css=<stylesheet url>][&lang=<language tag>]
  *