@missing-elements/h5p-verify 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 missing-elements
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @missing-elements/h5p-verify
+
+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.
+
+```bash
+npx @missing-elements/h5p-verify course.h5p
+```
+
+```
+pass  course.h5p  ready in 0.37 s  revision sha256:872ee6f732e6a4b7…
+  screenshot: course.verify/screenshot.png
+```
+
+```
+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
+```
+
+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 |
+
+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.
+
+## Options
+
+| | |
+|---|---|
+| `--libraries hub\|<url>` | for a package exported without library folders, what h5p.com and h5p.org do by default |
+| `--out <dir>` | where the report and screenshot go |
+| `--browser <path>` | a Chromium-based browser; otherwise Chrome, then Edge, then Playwright's own 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 |
+
+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.
+
+## From code
+
+```js
+import { verifyPackage, summarize } from '@missing-elements/h5p-verify'
+
+const report = await verifyPackage({ file: 'course.h5p', out: 'report/' })
+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.
+
+## Licence
+
+MIT. It runs the player, whose H5P runtime is GPL-3.0; see the player's
+[NOTICE.md](https://github.com/missing-elements/h5p-offline-player/blob/main/packages/player/NOTICE.md).

package/bin/h5p-verify.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { basename, dirname, join, resolve } from 'node:path'
+import { VerifyError, summarize, verifyPackage } from '../lib/verify.mjs'
+
+const HELP = `Usage: h5p-verify <package.h5p> [options]
+
+Plays the package in a headless browser through h5p-offline-player and reports whether it
+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
+  --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
+  --ready <seconds>      time allowed to reach ready (default 60)
+  --settle <seconds>     time watched after ready for late errors (default 3)
+  --json                 print the report as JSON instead of the summary
+  -q, --quiet            only the verdict line
+  -h, --help
+`
+
+let args
+try {
+  args = parseArgs({
+    allowPositionals: true,
+    options: {
+      libraries: { type: 'string' },
+      out: { type: 'string' },
+      browser: { type: 'string' },
+      ready: { type: 'string' },
+      settle: { type: 'string' },
+      json: { type: 'boolean' },
+      quiet: { type: 'boolean', short: 'q' },
+      help: { type: 'boolean', short: 'h' }
+    }
+  })
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error))
+  console.error(HELP)
+  process.exit(2)
+}
+
+const [file] = args.positionals
+if (args.values.help || !file) {
+  console.log(HELP)
+  process.exit(args.values.help ? 0 : 2)
+}
+
+const seconds = (value, fallback) => {
+  if (value === undefined) return fallback
+  const number = Number(value)
+  if (!Number.isFinite(number) || number <= 0) {
+    console.error(`Not a number of seconds: ${value}`)
+    process.exit(2)
+  }
+  return number * 1000
+}
+
+const out = args.values.out ?? join(dirname(resolve(file)), `${basename(file, '.h5p')}.verify`)
+
+try {
+  const report = await verifyPackage({
+    file,
+    libraries: args.values.libraries,
+    out,
+    browser: args.values.browser,
+    readyTimeout: seconds(args.values.ready, 60_000),
+    settle: seconds(args.values.settle, 3_000)
+  })
+  if (args.values.json) console.log(JSON.stringify(report, null, 2))
+  else if (args.values.quiet) console.log(summarize(report).split('\n')[0])
+  else console.log(summarize(report))
+  process.exit(report.verdict === 'pass' ? 0 : 1)
+} catch (error) {
+  console.error(error instanceof VerifyError ? error.message : error)
+  process.exit(2)
+}

package/lib/page.html

@@ -0,0 +1,48 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>h5p-verify</title>
+    <script type="module" src="/h5p-player.js"></script>
+    <style>
+      body { margin: 0; padding: 16px; background: #fff; font: 14px system-ui, sans-serif; }
+      h5p-player { display: block; width: 1024px; min-height: 240px; }
+    </style>
+  </head>
+  <body>
+    <input type="file" id="file" hidden />
+    <h5p-player auto-resize></h5p-player>
+    <script>
+      // What the driver reads back: every state, error and statement the element reported,
+      // stamped with the page's clock so the report can say how long the boot took.
+      const report = (window.__verify = { started: null, states: [], errors: [], xapi: [] })
+      const player = document.querySelector('h5p-player')
+      const libraries = new URLSearchParams(location.search).get('libraries')
+      if (libraries) player.setAttribute('libraries', libraries)
+
+      player.addEventListener('statechange', (event) => {
+        report.states.push({ state: event.detail.state, at: performance.now() })
+      })
+      player.addEventListener('error', (event) => {
+        report.errors.push({
+          code: event.detail.code,
+          message: event.detail.message,
+          missingLibraries: event.detail.missingLibraries ?? null,
+          // A runtime error once the content is up leaves the state at `ready`: the content
+          // kept running. Before that it is the boot failing.
+          afterReady: player.state === 'ready',
+          at: performance.now()
+        })
+      })
+      player.addEventListener('xapi', (event) => {
+        report.xapi.push(event.detail.verb ?? null)
+      })
+      document.querySelector('#file').addEventListener('change', (event) => {
+        const [file] = event.target.files
+        if (!file) return
+        report.started = performance.now()
+        player.file = file
+      })
+    </script>
+  </body>
+</html>

package/lib/verify.mjs

@@ -0,0 +1,278 @@
+import { createServer } from 'node:http'
+import { createRequire } from 'node:module'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { basename, dirname, extname, join, normalize, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { chromium } from 'playwright-core'
+
+/**
+ * Plays a package the way a learner would — the real element, the real Service Worker, a real
+ * browser — and reports what happened. The package is handed to the element as a picked file,
+ * the same path the installable app uses, so nothing here needs `Range` support or a network.
+ *
+ * What the report can say: the package indexed (or which libraries it lacks), the runtime
+ * booted, nothing threw before `ready`, the content drew something, and what the frame asked
+ * for that was not there. What it cannot say: whether the content is any good.
+ */
+
+const require = createRequire(import.meta.url)
+const here = fileURLToPath(new URL('.', import.meta.url))
+const { version } = require('../package.json')
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json',
+  '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+  '.ttf': 'font/ttf',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8'
+}
+
+/**
+ * @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} [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
+ * @property {number} [settle] ms watched after `ready` for late errors; default 3 000
+ */
+
+/**
+ * @param {VerifyOptions} options
+ */
+export async function verifyPackage(options) {
+  const file = resolve(options.file)
+  const size = (await stat(file).catch(() => null))?.size
+  if (size === undefined) throw new VerifyError(`No such file: ${file}`)
+  const readyTimeout = options.readyTimeout ?? 60_000
+  const settle = options.settle ?? 3_000
+
+  const server = await serve(await playerDist())
+  const browser = await launch(options.browser)
+  try {
+    const context = await browser.newContext({ viewport: { width: 1100, height: 800 } })
+    // Runs in every document, the frame included: a CSP violation fires an event in the document
+    // it happens in, and nothing else reports it.
+    await context.addInitScript(() => {
+      const list = []
+      Object.defineProperty(window, '__csp', { value: list })
+      document.addEventListener('securitypolicyviolation', (event) => {
+        list.push({ directive: event.violatedDirective, blocked: event.blockedURI })
+      })
+    })
+    const page = await context.newPage()
+
+    const consoleErrors = []
+    const failedRequests = []
+    page.on('console', (message) => {
+      // A failed load is on the response listener, with the probe 404s filtered out; the
+      // console's copy of it names no URL and would only repeat it.
+      if (message.type() === 'error' && !message.text().startsWith('Failed to load resource')) consoleErrors.push(message.text())
+    })
+    page.on('response', (response) => {
+      const url = response.url()
+      // The runtime probes `library.json` under the versioned and the unversioned folder name and
+      // takes whichever answers; one of the two is always a 404, and it is load-bearing.
+      if (response.status() >= 400 && url.startsWith(server.url) && !url.endsWith('/library.json')) {
+        failedRequests.push({ url: url.slice(server.url.length), status: response.status() })
+      }
+    })
+    page.on('requestfailed', (request) => {
+      const url = request.url()
+      const error = request.failure()?.errorText ?? 'failed'
+      // An abort is the requester's own doing — a media element drops a range request every
+      // time it seeks — and says nothing about the package.
+      if (url.startsWith(server.url) && error !== 'net::ERR_ABORTED') failedRequests.push({ url: url.slice(server.url.length), error })
+    })
+
+    const query = options.libraries ? `?libraries=${encodeURIComponent(options.libraries)}` : ''
+    await page.goto(`${server.url}/${query}`)
+    await page.setInputFiles('#file', file)
+
+    let timedOut = false
+    await page
+      .waitForFunction(() => window.__verify.states.some((s) => s.state === 'ready' || s.state === 'error'), null, { timeout: readyTimeout })
+      .catch(() => {
+        timedOut = true
+      })
+    if (!timedOut) await page.waitForTimeout(settle)
+
+    const collected = await page.evaluate(() => {
+      const player = document.querySelector('h5p-player')
+      return { ...window.__verify, state: player.state, revision: player.revision }
+    })
+    const frame = page.frames().find((candidate) => candidate.url().includes('/h5p/frame/'))
+    const rendered = frame
+      ? await frame
+          .evaluate(() => {
+            const root = document.querySelector('#h5p-root')
+            const rect = root?.getBoundingClientRect()
+            return {
+              height: rect ? Math.round(rect.height) : 0,
+              elements: root ? root.querySelectorAll('*').length : 0,
+              text: (root?.innerText ?? '').trim().length,
+              instances: window.H5P?.instances?.length ?? null
+            }
+          })
+          .catch(() => null)
+      : null
+    const csp = frame ? await frame.evaluate(() => window.__csp ?? []).catch(() => []) : []
+
+    let screenshot = null
+    if (options.out && collected.state === 'ready') {
+      await mkdir(options.out, { recursive: true })
+      screenshot = join(options.out, 'screenshot.png')
+      await page.locator('h5p-player').screenshot({ path: screenshot })
+    }
+
+    const ready = collected.states.find((s) => s.state === 'ready')
+    const report = {
+      tool: `h5p-verify ${version}`,
+      file,
+      size,
+      libraries: options.libraries ?? null,
+      verdict: 'pass',
+      reasons: [],
+      warnings: [],
+      state: collected.state,
+      readyMs: ready && collected.started !== null ? Math.round(ready.at - collected.started) : null,
+      revision: collected.revision ?? null,
+      errors: collected.errors.map(({ at, ...error }) => error),
+      rendered,
+      xapi: [...new Set(collected.xapi)],
+      csp,
+      failedRequests,
+      console: consoleErrors.filter((text) => !collected.errors.some((error) => text.includes(error.message))).slice(0, 20),
+      screenshot
+    }
+
+    if (timedOut) {
+      report.verdict = 'fail'
+      report.reasons.push(`did not reach ready within ${readyTimeout / 1000} s; last state: ${collected.state}`)
+    } else if (collected.state !== 'ready') {
+      report.verdict = 'fail'
+      for (const error of report.errors.filter((e) => !e.afterReady)) report.reasons.push(`${error.code}: ${error.message}`)
+      if (report.reasons.length === 0) report.reasons.push(`state is ${collected.state}`)
+    } else if (!rendered || rendered.height < 1 || rendered.elements === 0) {
+      report.verdict = 'fail'
+      report.reasons.push('the content started but drew nothing: the frame is empty')
+    }
+    // An uncaught error while the runtime boots is a defect in the package even when the content
+    // comes up around it — a library listed that is not a runtime library, a script that reaches
+    // for something absent — and the part that threw is missing from what was drawn. One after
+    // `ready` is the content running, and content types throw non-fatal exceptions routinely.
+    const booting = report.errors.filter((e) => e.code === 'runtime' && !e.afterReady)
+    if (report.verdict === 'pass' && booting.length > 0) {
+      report.verdict = 'fail'
+      report.reasons.push(`${booting.length} uncaught error${booting.length === 1 ? '' : 's'} while booting: ${dedupe(booting.map((e) => e.message)).join('; ')}`)
+    }
+    for (const message of dedupe(report.errors.filter((e) => e.afterReady).map((e) => e.message))) report.warnings.push(`runtime error after ready: ${message}`)
+    for (const { url, status, error } of failedRequests) report.warnings.push(`request failed: ${url} (${status ?? error})`)
+    for (const { directive, blocked } of csp) report.warnings.push(`blocked by the frame's CSP: ${blocked} (${directive})`)
+    for (const text of report.console) report.warnings.push(`console error: ${text.slice(0, 200)}`)
+
+    if (options.out) {
+      await mkdir(options.out, { recursive: true })
+      await writeFile(join(options.out, 'report.json'), `${JSON.stringify(report, null, 2)}\n`)
+    }
+    return report
+  } finally {
+    await browser.close()
+    server.close()
+  }
+}
+
+export class VerifyError extends Error {}
+
+/** The distinct messages, each with how often it occurred: `… (×4)`. */
+function dedupe(messages) {
+  const counts = new Map()
+  for (const message of messages) counts.set(message, (counts.get(message) ?? 0) + 1)
+  return [...counts].map(([message, count]) => (count > 1 ? `${message} (×${count})` : message))
+}
+
+/** The player's `dist/`, from the installed package; the workspace needs it built first. */
+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'))) {
+    throw new VerifyError(`The player is not built at ${dist} — run \`pnpm build\` in the workspace, or reinstall the package`)
+  }
+  return dist
+}
+
+/** A static server for the player and the test page, on a free localhost port. */
+function serve(dist) {
+  const page = join(here, 'page.html')
+  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)) {
+      response.writeHead(403).end()
+      return
+    }
+    try {
+      const body = await readFile(target)
+      response.writeHead(200, {
+        'Content-Type': MIME[extname(target)] ?? 'application/octet-stream',
+        'Content-Length': body.length,
+        'Cache-Control': 'no-store'
+      })
+      response.end(body)
+    } catch {
+      response.writeHead(404, { 'Content-Type': 'text/plain' }).end('not found')
+    }
+  })
+  return new Promise((resolveServer) => {
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = /** @type {import('node:net').AddressInfo} */ (server.address())
+      resolveServer({ url: `http://127.0.0.1:${port}`, close: () => server.close() })
+    })
+  })
+}
+
+/**
+ * A Chromium: the one named, else Chrome or Edge installed on the machine, else Playwright's
+ * own. Chrome and Edge first because they are usually there and cost no download.
+ */
+async function launch(executablePath) {
+  const attempts = executablePath
+    ? [{ executablePath }]
+    : [{ channel: 'chrome' }, { channel: 'msedge' }, {}]
+  const failures = []
+  for (const attempt of attempts) {
+    try {
+      return await chromium.launch({ headless: true, ...attempt })
+    } catch (error) {
+      failures.push(error instanceof Error ? error.message.split('\n')[0] : String(error))
+    }
+  }
+  throw new VerifyError(
+    'No browser could be started. Install Google Chrome or Microsoft Edge, run `npx playwright install chromium`, ' +
+      `or pass --browser <path>.\n  ${failures.join('\n  ')}`
+  )
+}
+
+/** A one-line, human-readable account of a report, for the command and for logs. */
+export function summarize(report) {
+  const name = basename(report.file)
+  const took = report.readyMs !== null ? `ready in ${(report.readyMs / 1000).toFixed(2)} s` : `state ${report.state}`
+  const lines = [`${report.verdict}  ${name}  ${took}${report.revision ? `  revision ${report.revision.slice(0, 23)}…` : ''}`]
+  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`)
+  }
+  for (const warning of report.warnings) lines.push(`  warning: ${warning}`)
+  if (report.screenshot) lines.push(`  screenshot: ${report.screenshot}`)
+  return lines.join('\n')
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@missing-elements/h5p-verify",
+  "version": "0.1.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/missing-elements/h5p-offline-player.git",
+    "directory": "packages/verify"
+  },
+  "homepage": "https://github.com/missing-elements/h5p-offline-player/tree/main/packages/verify#readme",
+  "bugs": {
+    "url": "https://github.com/missing-elements/h5p-offline-player/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "h5p-verify": "./bin/h5p-verify.mjs"
+  },
+  "exports": {
+    ".": "./lib/verify.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "keywords": [
+    "h5p",
+    "verify",
+    "test",
+    "playwright",
+    "headless",
+    "elearning",
+    "cli",
+    "agent-skill"
+  ],
+  "dependencies": {
+    "playwright-core": "^1.50.0",
+    "@missing-elements/h5p-offline-player": "^0.1.9"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "@zip.js/zip.js": "^2.17.0",
+    "typescript": "^5.7.3",
+    "vitest": "^5.0.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "pnpm --filter @missing-elements/h5p-offline-player build && vitest run",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}