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
28 changes: 23 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -1465,11 +1465,29 @@ driver along and the normalizer should not.
and warning means and what to do about it, to look at the screenshot because layout mistakes
raise no error, never to make the check pass by removing what fails, and what a pass does not
claim: nothing about the content's correctness, level, licensing or accessibility.

Not built, deliberately: steps that click through the content and check the xAPI it sends, a
content digest for reviewing what was generated, and a check of library versions against the
hub's catalogue — the last of which is the commonest reason a package that plays here is refused
on upload, since h5p-cli builds from GitHub `master` and h5p.com carries the hub's versions.
- **`--untrusted` plays a package as a site that did not make it does** (2026-10-18, #38): the
element's `untrusted`, read back from it for the report rather than taken from the option, the
libraries from `--libraries` or the element's own `pack`. What the content check changed is
measured, not told: the runtime's notes, which the boot script writes to the frame's console and
the report keeps, cover six kinds of change and none of the markup it strips. So the verifier
fetches the package's `content.json` through the frame with `X-H5P-Content-Check: semantics`,
which the worker answers with the file as written, and compares it with the parameters the boot
script left in `H5PIntegration` (`contentChanges`): tags removed by name, attributes and style
properties counted only on the kinds of tag still there (a form removed whole is one line, not
its inputs' attributes too), fields and list items removed, values changed; a removed empty value
is left out, as upstream drops those too. The content upgrade runs before the check and can move
fields when the pack is newer than the content, so a change that is not markup is not attributed
to the check. Every change is a warning, never a failure: the content plays, as it would on the
site. A package that needs its own copy of a library is refused with `carried`, and the summary
says to build against the pack's versions or play it trusted. `--libraries` takes a bundle on
disk too, served from the verifier's own server at `/__libraries/<n>.h5p`, so the check runs
offline against a pack the caller names; the tests use the workspace's.

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
catalogue, the commonest reason a package that plays here is refused on upload (h5p-cli builds
from GitHub `master`, and h5p.com carries the hub's versions), is not built either; `--untrusted`
checks them against the pack's, which follows the hub weekly.
The tests need the player built (`pnpm build`); the package's `test` script does that first.
The repository's own sweep does click through content and read its statements (next section),
for packages it makes; the verifier, which is handed a stranger's, still does not.
Expand Down
3 changes: 2 additions & 1 deletion docs/untrusted.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,4 +116,5 @@ With or without `untrusted`:
there. For a site with signed-in users, [Embed](https://github.com/missing-elements/h5p-offline-player#embed)
puts the player on a separate domain as well.
- **Correctness.** The check is about safety. Whether a package works at all is what
[`h5p-verify`](verify.md) answers.
[`h5p-verify`](verify.md) answers; `h5p-verify --untrusted` plays it the way your site will, and
lists what the check removes from it.
4 changes: 3 additions & 1 deletion docs/verify.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ npx @missing-elements/h5p-verify course.h5p # exit 0: it plays; 1: it doe
```

It names missing libraries, fails on an uncaught error while the runtime boots, and checks that
the content drew something. It is meant as the last step of a pipeline that generates or
the content drew something. With `--untrusted` it plays the package as a site that did not make
it will, [untrusted](untrusted.md), against the library pack, and lists as warnings what the
content check removes from each field: markup, attributes and styles by name, fields, values. 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.
29 changes: 27 additions & 2 deletions packages/verify/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,36 @@ reaches `ready`, that nothing throws while booting (an error after `ready` is a
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.

## Played untrusted

A site that plays packages it did not make plays them
[`untrusted`](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/untrusted.md),
as the H5P plugins treat an upload: none of the package's own code runs, its libraries come only
from the site's pack, and its content is checked against each library's `semantics.json`.
`--untrusted` plays it that way:

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

```
pass course.h5p ready in 0.83 s revision sha256:c4fd49473b30cd97…
warning: content check: content[2].content.params.text: markup removed: <form>, <label> ×2, <input> ×2, <button>
warning: content check: content[3].content.params.text: attributes removed: style; style removed: display, padding, border-radius, background-color, color, text-decoration
```

Each warning is a field the content will lose on such a site, measured by comparing the package's
`content.json` with what the runtime was handed. They are warnings because the content still plays.
A package built against a library newer than the pack is refused, with what to do. The libraries
come from the pack on jsDelivr unless `--libraries` names another; name a copy on disk, such as
`node_modules/@missing-elements/h5p-libraries/libraries.h5p`, to run the check offline.

## Options

| | |
|---|---|
| `--libraries pack\|<url>` | supply libraries for a package exported without them: `pack` is the library pack (`hub` means the same) |
| `--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; `hub` means the same), a bundle's URL, or a bundle on disk, which the verifier serves itself |
| `--out <dir>` | where the report and screenshot go |
| `--browser <path>` | a Chromium-based browser; otherwise Chrome, then Edge, then Playwright's Chromium |
| `--ready <s>` | time allowed to reach `ready`, default 60 |
Expand All @@ -48,7 +73,7 @@ Needs Node 20 or later and a Chromium-based browser; without Chrome or Edge, run
```js
import { verifyPackage, summarize } from '@missing-elements/h5p-verify'

const report = await verifyPackage({ file: 'course.h5p', out: 'report/' })
const report = await verifyPackage({ file: 'course.h5p', out: 'report/', untrusted: true })
console.log(summarize(report))
if (report.verdict !== 'pass') process.exit(1)
```
Expand Down
11 changes: 9 additions & 2 deletions packages/verify/bin/h5p-verify.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,13 @@ 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 pack|<url> supply libraries for a package exported without its own (pack: the
published library pack; hub means the same)
--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
the check removed is reported as warnings
--libraries <sources> where libraries come from, tried in order: pack (the published
library pack; hub means the same), a bundle's URL, or a bundle on
disk, such as a copy of the pack, which keeps the check offline
--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
Expand All @@ -27,6 +32,7 @@ try {
allowPositionals: true,
options: {
libraries: { type: 'string' },
untrusted: { type: 'boolean' },
out: { type: 'string' },
browser: { type: 'string' },
ready: { type: 'string' },
Expand Down Expand Up @@ -64,6 +70,7 @@ try {
const report = await verifyPackage({
file,
libraries: args.values.libraries,
untrusted: args.values.untrusted,
out,
browser: args.values.browser,
readyTimeout: seconds(args.values.ready, 60_000),
Expand Down
5 changes: 4 additions & 1 deletion packages/verify/lib/page.html
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,11 @@
// 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')
const query = new URLSearchParams(location.search)
const libraries = query.get('libraries')
if (libraries) player.setAttribute('libraries', libraries)
// Played as a site plays a package it did not make: none of its own code, the content checked.
if (query.has('untrusted')) player.untrusted = true

player.addEventListener('statechange', (event) => {
report.states.push({ state: event.detail.state, at: performance.now() })
Expand Down
Loading
Loading