@missing-elements/h5p-verify 0.1.0 → 0.1.2

package/README.md

@@ -2,11 +2,7 @@
 
 Plays an `.h5p` package in a headless browser through
 [h5p-offline-player](https://github.com/missing-elements/h5p-offline-player) and reports whether
-it works. The last check before a package — generated, edited, repackaged — is handed to anyone.
-
-A zip that opens and JSON that parses prove nothing: most broken packages are valid zips that
-fail in the H5P runtime, or start and draw the wrong thing. This runs the real runtime, with no
-server and no account, in a few seconds.
+it works.
 
 ```bash
 npx @missing-elements/h5p-verify course.h5p
@@ -19,45 +15,33 @@ pass  course.h5p  ready in 0.37 s  revision sha256:872ee6f732e6a4b7…
 
 ```
 fail  course.h5p  state error
-  bad-archive: This package contains no libraries, only content. … Missing: H5P.QuestionSet-1.20
-  fix: add the library folders (H5P.QuestionSet-1.20), or --libraries hub if the destination site supplies libraries
+  bad-archive: This package contains no libraries, only content. … Missing: H5P.QuestionSet-1.21
+  fix: add the library folders (H5P.QuestionSet-1.21), or --libraries pack if the destination site supplies libraries
 ```
 
-Exit code 0 means it plays (there may be warnings), 1 that it does not, 2 that the check could
-not run. `report.json` and `screenshot.png` land in `<package>.verify/` beside the package.
-
-## What it checks
-
-| | |
-|---|---|
-| The archive | indexed by the player: `h5p.json`, entry names, the libraries it declares against the folders it carries |
-| Libraries | missing ones are named; `--libraries hub` or `--libraries <url>` supplies them the way a host would |
-| Boot | the runtime reaches `ready`, and how long that took |
-| Errors | an uncaught error while booting fails the check even when the content comes up around it; one after `ready` is a warning, since content types throw non-fatal exceptions routinely |
-| Rendering | the content drew something: the frame's root has a height and elements |
-| Requests | anything the frame asked for and did not get, such as a media file `content.json` names that is not in the archive |
-| CSP | an outside origin the frame's policy blocked |
-| Provenance | the `revision` every xAPI statement from this build will carry |
+Exit code 0: it plays (possibly with warnings); 1: it does not; 2: the check could not run.
+`report.json` and `screenshot.png` land in `<package>.verify/`.
 
-What it does not check: whether the content is correct, suited to its learners, accessible, or
-properly licensed. Look at the screenshot; a package can start cleanly and still be laid out
-wrong.
+It checks that the archive indexes and carries the libraries it declares, that the runtime
+reaches `ready`, that nothing throws while booting (an error after `ready` is a warning), that the
+content drew something, and it lists failed requests, CSP blocks and the build's `revision`. It
+does not judge correctness, suitability, accessibility or licensing: look at the screenshot.
 
 ## Options
 
 | | |
 |---|---|
-| `--libraries hub\|<url>` | for a package exported without library folders, what h5p.com and h5p.org do by default |
+| `--libraries pack\|<url>` | supply libraries for a package exported without them: `pack` is the library pack (`hub` means the same) |
 | `--out <dir>` | where the report and screenshot go |
-| `--browser <path>` | a Chromium-based browser; otherwise Chrome, then Edge, then Playwright's own Chromium |
+| `--browser <path>` | a Chromium-based browser; otherwise Chrome, then Edge, then Playwright's Chromium |
 | `--ready <s>` | time allowed to reach `ready`, default 60 |
 | `--settle <s>` | time watched after `ready` for late errors, default 3 |
 | `--json` | the report as JSON on stdout |
-| `-q` | the verdict line only |
+| `-q`, `--quiet` | the verdict line only |
+| `-h`, `--help` | |
 
-Needs Node 20 or later and a Chromium-based browser. Chrome or Edge on the machine is used
-if there is one; otherwise `npx playwright install chromium` fetches one (about 150 MB, once).
-Headless, so no display is needed.
+Needs Node 20 or later and a Chromium-based browser; without Chrome or Edge, run
+`npx playwright install chromium`.
 
 ## From code
 
@@ -69,16 +53,8 @@ console.log(summarize(report))
 if (report.verdict !== 'pass') process.exit(1)
 ```
 
-## For agents
-
-The repository ships an [agent skill](https://agentskills.io), `skills/h5p-verify`, telling an AI
-agent that generates H5P content when to run this and how to read what comes back:
-
-```bash
-npx skills add missing-elements/h5p-offline-player --skill h5p-verify
-```
-
-or copy the folder into your agent's skills directory.
+An [agent skill](https://agentskills.io) for it ships in the repository:
+`npx skills add missing-elements/h5p-offline-player --skill h5p-verify`.
 
 ## Licence
 

package/bin/h5p-verify.mjs

@@ -9,7 +9,8 @@ Plays the package in a headless browser through h5p-offline-player and reports w
 works. Exit code 0: it plays (warnings possible). 1: it does not. 2: could not run.
 
 Options:
-  --libraries hub|<url>  supply libraries for a package exported without its own
+  --libraries pack|<url> supply libraries for a package exported without its own (pack: the
+                         published library pack; hub means the same)
   --out <dir>            where report.json and screenshot.png go
                          (default: <package>.verify/ beside the package)
   --browser <path>       a Chromium-based browser; Chrome, Edge or Playwright's found otherwise

package/lib/verify.mjs

@@ -39,7 +39,7 @@ const MIME = {
 /**
  * @typedef {object} VerifyOptions
  * @property {string} file the `.h5p` to play
- * @property {string} [libraries] `hub`, or the URL of a bundle, for a package without library folders
+ * @property {string} [libraries] `pack`, or the URL of a bundle, for a package without library folders
  * @property {string} [out] where `report.json` and `screenshot.png` go; nothing is written without it
  * @property {string} [browser] a Chromium-based browser executable; found automatically otherwise
  * @property {number} [readyTimeout] ms allowed to reach `ready`; default 60 000
@@ -200,23 +200,33 @@ function dedupe(messages) {
   return [...counts].map(([message, count]) => (count > 1 ? `${message} (×${count})` : message))
 }
 
-/** The player's `dist/`, from the installed package; the workspace needs it built first. */
+/**
+ * The player's `dist/` and the runtime's, from the installed packages; the workspace needs both
+ * built first. The runtime is a package of its own (`@missing-elements/h5p-runtime`, GPL) and is
+ * served at `/frame-assets/`, which is where the element looks beside its own script.
+ */
 async function playerDist() {
   const element = require.resolve('@missing-elements/h5p-offline-player')
   const dist = dirname(element)
-  if (!existsSync(join(dist, 'h5p-sw.js')) || !existsSync(join(dist, 'frame-assets', 'h5p.css'))) {
+  if (!existsSync(join(dist, 'h5p-sw.js'))) {
     throw new VerifyError(`The player is not built at ${dist} — run \`pnpm build\` in the workspace, or reinstall the package`)
   }
-  return dist
+  const runtime = join(dirname(require.resolve('@missing-elements/h5p-runtime/package.json')), 'dist')
+  if (!existsSync(join(runtime, 'h5p.css')) || !existsSync(join(runtime, 'frame-boot.js'))) {
+    throw new VerifyError(`The H5P runtime is not built at ${runtime} — run \`pnpm build\` in the workspace, or reinstall @missing-elements/h5p-runtime`)
+  }
+  return { dist, runtime }
 }
 
-/** A static server for the player and the test page, on a free localhost port. */
-function serve(dist) {
+/** A static server for the player, the runtime and the test page, on a free localhost port. */
+function serve({ dist, runtime }) {
   const page = join(here, 'page.html')
+  const ASSETS = '/frame-assets/'
   const server = createServer(async (request, response) => {
     const path = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname)
-    const target = path === '/' ? page : join(dist, normalize(path).replace(/^(\.\.[/\\])+/, ''))
-    if (target !== page && !target.startsWith(dist)) {
+    const safe = (root, rest) => join(root, normalize(rest).replace(/^(\.\.[/\\])+/, ''))
+    const target = path === '/' ? page : path.startsWith(ASSETS) ? safe(runtime, path.slice(ASSETS.length)) : safe(dist, path)
+    if (target !== page && !target.startsWith(dist) && !target.startsWith(runtime)) {
       response.writeHead(403).end()
       return
     }
@@ -270,7 +280,7 @@ export function summarize(report) {
   for (const reason of report.reasons) lines.push(`  ${reason}`)
   const missing = report.errors.find((error) => error.missingLibraries)?.missingLibraries
   if (missing) {
-    lines.push(`  fix: add the library folders (${missing.folders.join(', ')}), or --libraries hub if the destination site supplies libraries`)
+    lines.push(`  fix: add the library folders (${missing.folders.join(', ')}), or --libraries pack if the destination site supplies libraries`)
   }
   for (const warning of report.warnings) lines.push(`  warning: ${warning}`)
   if (report.screenshot) lines.push(`  screenshot: ${report.screenshot}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@missing-elements/h5p-verify",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Plays an .h5p package in a headless browser through h5p-offline-player and reports whether it works: start-up, errors, missing libraries, a screenshot. The last check before a generated package is handed to anyone.",
   "license": "MIT",
   "repository": {
@@ -39,13 +39,14 @@
   ],
   "dependencies": {
     "playwright-core": "^1.50.0",
-    "@missing-elements/h5p-offline-player": "^0.1.9"
+    "@missing-elements/h5p-offline-player": "^0.6.0",
+    "@missing-elements/h5p-runtime": "^0.1.0"
   },
   "devDependencies": {
-    "@types/node": "^22.13.0",
-    "@zip.js/zip.js": "^2.17.0",
-    "typescript": "^5.7.3",
-    "vitest": "^5.0.1"
+    "@types/node": "^26.6.4",
+    "@zip.js/zip.js": "^2.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=20"