diff --git a/AGENTS.md b/AGENTS.md index 0c038230..73d7393d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/.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. diff --git a/docs/untrusted.md b/docs/untrusted.md index 2078c734..2060e1b9 100644 --- a/docs/untrusted.md +++ b/docs/untrusted.md @@ -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. diff --git a/docs/verify.md b/docs/verify.md index 57de089a..3c8cb191 100644 --- a/docs/verify.md +++ b/docs/verify.md @@ -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. diff --git a/packages/verify/README.md b/packages/verify/README.md index e34e994b..38762296 100644 --- a/packages/verify/README.md +++ b/packages/verify/README.md @@ -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:
,