Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,8 +155,11 @@ packages/normalize/ @missing-elements/h5p-normalize — the package rewrit
packages/verify/ @missing-elements/h5p-verify — plays a package headless and reports whether it works
bin/h5p-verify.mjs the command
lib/verify.mjs the static server, the browser run and the report; lib/page.html the page it drives
lib/preview.mjs `--preview`: the package in the person's own browser, served by range
until its last tab has closed; lib/preview.html its page
tests/ node tests that run the real thing against the demo's committed content;
package-types.ts as for the normalizer
package-types.ts as for the normalizer; preview.test.ts the preview's
ranges, a browser playing from it, its ending and its command line
types/ generated, not in git: the declarations, `VerifyReport` among them

packages/cmi5/ @missing-elements/h5p-cmi5 — cmi5 for the element, published as a library
Expand Down Expand Up @@ -1701,6 +1704,32 @@ driver along and the normalizer should not.
content was checked as the site will play it. Writing the test found the demo's own quiz, built
in March, older than the pack by a patch or two in four libraries, H5P.Video 1.6.68 against
1.6.79 among them.
- **`--preview` is the person's half of the check** (2026-10-23, #69). The check says whether a
package starts. Whether it is right, a person judges by playing it, the same way for every content
type; an answer key or scripted screenshots would be one more thing to write per type. So
`--preview` checks nothing. It serves the package and a page of its own from the verifier's
server, with the same player, runtime and library sources, and opens the default browser on
it. Three choices in it:
- **The package is served with `Range`, as a static host serves it**, not handed over as a
picked file, which a page cannot get without a click. That means `206`, `Content-Range`, and an
`ETag` from the file's size and time, so a file written again is a new package to the element.
The element reads it `range-http`: the libraries in the warm's few requests, media by the
ranges asked for. Measured on 2026-10-23 with a 32 MB stored video added beside the demo's
clip: of 36.1 MB, 1.58 MB in 9 requests reached `ready`, and a range of that video cost a
kilobyte. Every request was ranged. In Chrome, Firefox and WebKit the clip played.
- **It ends by itself.** The page holds an event stream open. The server ends ten seconds after
the last stream closes, which a reload reconnects within, or ten minutes after starting if
none ever opened. The page stops reconnecting once its server has gone, so a stale tab cannot
keep a later preview on the same port alive.
- **It takes port 4645 when that port is free.** Every preview then shares one origin's worker
and caches, instead of leaving a new origin's behind for each run. When another preview or
another program holds the port, it takes any free one.

The check's own options are refused with it, not ignored. The browser opener is `open`,
`cmd /c start` or `xdg-open`, and the address is printed either way; it has not been tried on
Windows. The page sets `src` from the parsed URL's `href`, `http` or `https` only, as every page
that takes a package address from outside does (#71): its own route needs no check, but CodeQL
flagged the text going in, as `js/xss-through-dom`.

Not built, deliberately: steps that click through the content and check the xAPI it sends, and a
content digest for reviewing what was generated. A check of library versions against the hub's
Expand Down
3 changes: 2 additions & 1 deletion docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,8 @@ long as the player streams the result at least as well.

### The verifier, `@missing-elements/h5p-verify`

The command's options, its exit codes — 0 plays, 1 does not, 2 could not run — `report.json`, to
The command's options, its exit codes — 0 plays, 1 does not, 2 could not run; with `--preview`,
0 when the preview ends and 2 when it could not start — `report.json`, to
which fields may be added, and `verifyPackage()` and `summarize()`, with their types: `VerifyReport`
is `report.json`'s shape, and gains fields the same way. The verifier is a step in other
people's pipelines, so a check that turns a pass into a fail comes in a minor, never a patch; a new
Expand Down
9 changes: 9 additions & 0 deletions docs/verify.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,12 @@ With `--libraries pack`, or a copy of the pack's `parts/`, it plays a library th
at the pack's newer version, as a site with the pack will, and says which. It is meant as the last step of a pipeline that generates or
rewrites packages; the skill in `skills/h5p-verify/` tells an agent when to run it and how to
read the result.

The check cannot say whether the content is right; a person decides that by playing it.
`--preview` checks nothing and opens the package in the real player in the person's own
browser, served from their computer with `Range`, as a static host serves it. It works for any
content type, and a large video starts at once. It ends a few seconds after its last tab closes:

```bash
npx @missing-elements/h5p-verify@latest course.h5p --preview
```
29 changes: 29 additions & 0 deletions packages/verify/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,39 @@ A package built against a library newer than the pack is refused, with what to d
come from the pack on jsDelivr unless `--libraries` names another; name a copy on disk, such as
`node_modules/@missing-elements/h5p-libraries/parts`, to run the check offline.

## Preview

The check says whether a package starts. Whether it is right — the answers, a scenario's paths,
what happens at a video's timestamps — is for a person to judge, by playing it. `--preview`
checks nothing and opens the package in the real player in your browser, served from your
computer:

```bash
npx @missing-elements/h5p-verify@latest course.h5p --preview
```

```
Previewing course.h5p at http://127.0.0.1:4645/
The package stays on this computer. The preview ends when its tab is closed, or with Ctrl+C.
```

It plays any content type the player plays, with the same player, runtime and library sources
as the check, so `--untrusted`, `--libraries` and `--no-refresh-libraries` mean the same.

The package is served with `Range`, as a static host serves it. The libraries take a few
requests, and a video is read by the ranges the player asks for, so a large one starts at once
and nothing is read whole or extracted to disk.

The preview ends a few seconds after its last tab closes, so an agent can start it in the
background and leave it. `--no-open` prints the address instead of opening your default browser.
Exit code 0 when it ends, 2 when it could not start.

## Options

| | |
|---|---|
| `--preview` | check nothing: open the package in the real player in your browser, served from your computer, until its tab is closed |
| `--no-open` | with `--preview`, print the address instead of opening a browser |
| `--untrusted` | play it as a site plays a package it did not make, and report what the content check removed |
| `--libraries <sources>` | where libraries come from, tried in order: `pack` (the library pack), a bundle's URL, a bundle on disk, or a copy of the pack's `parts/` folder, which plays as `pack`; the verifier serves what is on disk itself. With the pack, a library the package carries plays at the pack's newer version, as on a site with the pack, and the summary lists each under `refreshed from the pack` |
| `--no-refresh-libraries` | play the libraries the package carries even where the pack has newer ones |
Expand Down
44 changes: 44 additions & 0 deletions packages/verify/bin/h5p-verify.mjs
Original file line number Diff line number Diff line change
@@ -1,14 +1,22 @@
#!/usr/bin/env node
import { parseArgs } from 'node:util'
import { basename, dirname, join, resolve } from 'node:path'
import { openBrowser, previewPackage } from '../lib/preview.mjs'
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.

With --preview it checks nothing: it opens the package in the real player in your browser,
served from this computer, until its tab is closed. Exit code 0 when the preview ends, 2 when
it could not start.

Options:
--preview open the package in your browser instead of checking it; it takes
--untrusted, --libraries and --no-refresh-libraries
--no-open with --preview, print the address instead of opening a browser
--untrusted play it as a site plays a package it did not make: none of its own
code runs, its libraries come only from --libraries (pack by
default), and its content is checked against their semantics. What
Expand All @@ -34,6 +42,8 @@ try {
args = parseArgs({
allowPositionals: true,
options: {
preview: { type: 'boolean' },
'no-open': { type: 'boolean' },
libraries: { type: 'string' },
untrusted: { type: 'boolean' },
'no-refresh-libraries': { type: 'boolean' },
Expand All @@ -58,6 +68,40 @@ if (args.values.help || !file) {
process.exit(args.values.help ? 0 : 2)
}

if (args.values['no-open'] && !args.values.preview) {
console.error('--no-open goes with --preview')
process.exit(2)
}

if (args.values.preview) {
// What only the check reads is refused rather than ignored, so a mistaken call says so.
const unsupported = ['out', 'browser', 'ready', 'settle', 'json', 'quiet'].filter((name) => args.values[name] !== undefined)
if (unsupported.length) {
console.error(`--preview does not take ${unsupported.map((name) => `--${name}`).join(', ')}`)
process.exit(2)
}
let preview
try {
preview = await previewPackage({
file,
libraries: args.values.libraries,
untrusted: args.values.untrusted,
refreshLibraries: !args.values['no-refresh-libraries']
})
} catch (error) {
console.error(error instanceof VerifyError ? error.message : error)
process.exit(2)
}
const address = `${preview.url}/`
console.log(`Previewing ${basename(file)} at ${address}`)
if (args.values['no-open'] || !(await openBrowser(address))) console.log('Open that address in a browser.')
console.log('The package stays on this computer. The preview ends when its tab is closed, or with Ctrl+C.')
for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => preview.close())
const ended = await preview.closed
console.log(ended === 'unopened' ? 'No tab opened the preview in time; it ended.' : 'The preview ended.')
process.exit(0)
}

const seconds = (value, fallback) => {
if (value === undefined) return fallback
const number = Number(value)
Expand Down
70 changes: 70 additions & 0 deletions packages/verify/lib/preview.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Preview</title>
<script type="module" src="/h5p-player.js"></script>
<style>
:root { color-scheme: light dark; }
body { margin: 0; background: Canvas; color: CanvasText; font: 15px/1.4 system-ui, sans-serif; }
header { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 16px; padding: 12px 16px; border-bottom: 1px solid GrayText; }
h1 { margin: 0; font-size: 1em; overflow-wrap: anywhere; }
#status { color: GrayText; }
main { max-width: 1024px; margin: 16px auto; padding: 0 16px; }
h5p-player { display: block; min-height: 240px; }
</style>
</head>
<body>
<header>
<h1 id="name">Preview</h1>
<span id="status" role="status">Opening…</span>
</header>
<main><h5p-player></h5p-player></main>
<script type="application/json" id="settings">{{settings}}</script>
<script>
const settings = JSON.parse(document.getElementById('settings').textContent)
const player = document.querySelector('h5p-player')
const status = document.getElementById('status')
document.title = `${settings.name} · preview`
document.getElementById('name').textContent = settings.name
// The element as the check sets it: the same libraries, played the same way.
if (settings.libraries) player.setAttribute('libraries', settings.libraries)
if (settings.packBase) player.setAttribute('pack-base', settings.packBase)
if (!settings.refreshLibraries) player.setAttribute('refresh-libraries', 'off')
if (settings.untrusted) player.untrusted = true

player.addEventListener('statechange', (event) => {
const { state } = event.detail
if (state === 'ready') {
status.textContent = settings.untrusted
? 'Played untrusted, as a site that did not make it plays it. Close this tab to end the preview.'
: 'Close this tab to end the preview.'
} else if (state !== 'error') status.textContent = 'Opening…'
})
player.addEventListener('error', (event) => {
// An error once the content is up leaves it running; before that, the package did not open.
if (player.state !== 'ready') status.textContent = event.detail.message
})
// Only a web address becomes `src`: never a `javascript:` or `data:` URL.
try {
const src = new URL(settings.src, window.location.href)
if (src.protocol === 'http:' || src.protocol === 'https:') {
player.setAttribute('src', src.href)
} else {
status.textContent = 'Invalid preview source.'
}
} catch {
status.textContent = 'Invalid preview source.'
}

// Held open while this tab shows the preview: the command ends once no tab does. Once its
// server has gone the page stops asking, so that it cannot keep a later preview alive.
const presence = new EventSource('/__preview/events')
presence.addEventListener('error', () => {
presence.close()
status.textContent = 'The preview has ended. Run the command again to open it.'
})
</script>
</body>
</html>
Loading
Loading