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
90 changes: 68 additions & 22 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,28 +184,35 @@ packages/author/ @missing-elements/h5p-author — a playable .h5p of an
source, published as a command (see *The author package*)
bin/h5p-author.mjs the command: `build` and `schema`
lib/build.mjs the source read and checked, the libraries loaded, the content generated,
media copied, layouts run, the parts planned with the player's `planPack`,
the archive written
media copied, the content checked as saved, the parts planned with the
player's `planPack`, the archive written
lib/check.mjs `checkContent`: content in the form H5P saves it checked, the layouts' `after`
run, for a tool that edits a saved package and for the build, which runs it
last on what it writes (#107); no Node import of its own
lib/libraries.mjs `loadLibraries`: the libraries content brings in, loaded and localized as
the build loads them, for the build and for a tool beside it; no Node
the build loads them, for the build and for a tool beside it;
`packageLibraries`, a package's own over the pack's (#107); no Node
import of its own, nor has lib/source-error.mjs, `SourceError` (#106)
lib/generator.mjs `ContentGenerator`: content from a type's `semantics.json`, authoring
(every written value checked as the editor's form would) or lenient, as
the sweep runs it; moved out of the demo on 2026-11-01 (#100)
(every written value checked as the editor's form would), lenient, as
the sweep runs it, or saved, as `checkContent` runs it; moved out of the
demo on 2026-11-01 (#100)
lib/types.mjs what the editor's own widgets set and check, per content type: Course
Presentation's layout, Interactive Video's placement, Branching
Scenario's paths, Game Map's stages, Find the Hotspot's areas
lib/text.mjs, translate.mjs, media.mjs, pack.mjs, schema.mjs, quiz.mjs text as H5P stores it; the
libraries' translations; files and web addresses; the pinned pack read
by part; the field list a source is written from; the first skill's
quiz format, still built
lib/text.mjs, translate.mjs, media.mjs, metadata.mjs, pack.mjs, schema.mjs, quiz.mjs text as H5P
stores it; the libraries' translations; files and web addresses; the
licences and roles H5P's metadata takes; the pinned pack read by part;
the field list a source is written from; the first skill's quiz format,
still built
scripts/ sync-skill.mjs writes the skill's type files' generated sections from the
pack (`pnpm --filter @missing-elements/h5p-author sync:skill`);
check-pack-published.mjs, the publish guard for the pinned pack and player
tests/ node tests: the generator, text and translations, layouts and schema, the
loader, builds with media from disk and a local server, the command, the
quiz format; fixtures/ the quiz format's two examples, which apps/skills
plays too; package-types.ts as for the normalizer
quiz format, the check of saved content, the demo's packages among it;
fixtures/ the quiz format's two examples, which apps/skills plays too;
package-types.ts as for the normalizer
types/ generated, not in git: the declarations

packages/cmi5/ @missing-elements/h5p-cmi5 — cmi5 for the element, published as a library
Expand Down Expand Up @@ -328,9 +335,11 @@ apps/skills/ the skills' test project, a project of the kind a skil
it installs the commands the skills run with npx, the author package and
the verifier, and the library pack; nothing in it ships. Out of the demo
since 2026-10-23, by the owner's choice
tests/author-verify.test.ts every h5p-author type file's example built, with sample media, and
played trusted and untrusted through the verifier's published API, each
a pass with no warnings; each file's generated section compared with
tests/author-verify.test.ts every h5p-author type file's example built, with sample media, checked
as saved content against the libraries it carries with nothing reported
and nothing changed (#107), and played trusted and untrusted through the
verifier's published API, each a pass with no warnings; each file's
generated section compared with
the pack's, so a pack refresh shows a change; and the quiz format, from
the author package's fixtures: both kinds, the eight-scenario example,
a quiz in Ukrainian and one whose titles and author carry quotes and
Expand Down Expand Up @@ -1989,9 +1998,10 @@ already holds text to the content check's rules, from the pack an untrusted chec
`apps/skills` plays every example untrusted too. Measured on a five-question quiz, at four
characters a token: `content.json` was about 3,470 tokens to write by hand, after reading 3,900 to
9,500 of a type's semantics; the source is 1,000 to 1,800 tokens, written from a type file of 200
to 3,000. Eight things the code does not say by itself:
to 3,000. Nine things the code does not say by itself:

- **One generator, two ways to run it.** `ContentGenerator` was the sweep's
- **One generator, three ways to run it.** The third, `saved`, checks content as H5P stores it
(*Saved content is checked as the build checks what it writes*, below). `ContentGenerator` was the sweep's
(`apps/demo/scripts/lib/sweep-content.mjs`), and moved here so there is one copy; the sweep runs
it `lenient`, keeping what its files write as written and filling every required field from its
own samples, and its 55 types came out byte for byte the same after the move. Authoring checks
Expand Down Expand Up @@ -2032,7 +2042,9 @@ to 3,000. Eight things the code does not say by itself:
given ids and types, neighbours named by label made indices both ways; end screens numbered. It
checks what those widgets would not let pass: a scenario node with no next, a link to no node, a
loop no path leaves; a map with no start; a hotspot question with no right area. A hidden field
nothing set is reported. Lists such a widget draws start empty.
nothing set is reported. Lists such a widget draws start empty. All of that runs on content in
the form H5P stores it, in `checkContent`, so it holds saved content too; only a layout's
`before`, Game Map's, works on the source, turning its numbers and labels into the stored text.
- **Media are copied and described.** A file is `{ path }`, beside the source or an `http(s)`
address, downloaded at build time; it lands under `content/images|videos|audios|files/` with its
MIME type, an image's size read from its header (PNG, JPEG, GIF, BMP; a JPEG's segments walked to
Expand Down Expand Up @@ -2074,9 +2086,42 @@ to 3,000. Eight things the code does not say by itself:
first: `scripts/check-pack-published.mjs` refuses to publish until the pinned version is on npm
and exports `./plan`, since a player published before it existed would install and fail on the
first import. A tool beside the build takes what the build loads (`openPack`, and `loadLibraries` over
any source with the pack's members) and its rules for text; not the build's check, which reads a
source where a tool edits saved content (#107). The runtime's library-name parser, content check
and content upgrade stay out: they are GPL-3.0-only.
any source with the pack's members), its rules for text, and since #107 the check it runs last
(next bullet). The runtime's library-name parser, content check and content upgrade stay out:
they are GPL-3.0-only.
- **Saved content is checked as the build checks what it writes** (2026-11-02, #107). A tool that
changes a saved package, the agent toolset's `apply` in embed-my/creator, could not take the
build's check, which reads a source: it refused every saved file (`mime`, `width`, `height`), every
part's metadata, a Game Map's stored stages and a field only an older minor has, and gave every
part a new `subContentId`, which the core names a part's statements by, so after each edit an LRS
would have counted every question as new. `checkContent` runs the generator `saved`: files and
metadata taken as saved and held to what the platforms keep of them (H5PContentValidator's
`_validateFilelike` and `validateLibrary`, and the licences the core's copyright dialog looks up
without a check, `lib/metadata.mjs`); each part's id kept, unless H5P would not keep it or an
earlier part has it, which copy and paste in the editor leaves; a markup field's text not wrapped
again. Then the layouts' `after`, the titles and the hidden fields nothing set, all moved out of
the build into it, and Game Map's checks with them, its `before` keeping only the conversion of a
source's numbers and labels. The build runs it last, on what it writes, and adds what it finds
except where the source has that problem already or the generator refused what was written
there, so the two hold content to one set of rules. The semantics, the owner's call the same day:
the package's own where it carries a library's major (`packageLibraries`, over the player's
`ownLibraries`), the pack's otherwise; where the content names another minor than the one checked
against, a field only that minor has is noted and kept, since the player upgrades it as it plays
(steps the runtime runs, GPL, in its frame) or plays newer content without it. Every type file's
example, built and then checked against its own libraries and against the pack, comes back with
nothing reported and nothing changed (`apps/skills`); the demo's packages report nothing but
`markup.h5p`'s markup, which it carries to be removed. Content written without its defaults, as
the demo's is, comes back with them, as the editor saves it. Run over the 88 real packages of the
owner's corpus, 61 report nothing; the others hold what their editor let an author save and the
build does not, a required alt text or scenario title left empty, keys an older editor wrote
(Drag and Drop's `dropZones[].type`, Branching Scenario's `contentId`), styles pasted from Word,
so a tool that changes one part keeps the problems under the paths it changed. Three things the
editor saves for an author who never touched them are taken as such, found on that corpus: an
optional group holding nothing an author has to write, empty texts in it included (Interactive
Video's adaptivity); the item it starts an optional list with (its subtitle track); and an
optional select at its empty choice (`goto.type: ""`). A group that is sub-content now gets an id
in a build too, as the editor's `initSubContent` gives one: Summary's statements and Single Choice
Set's choices had none, and Summary names a statement's statements by it.
- **The skill's type files are partly generated.** `skills/h5p-author/references/types/<Type>.md`
holds hand-written notes, an example, and the type's fields between two markers, written by
`schemaOf(…, { markdown: true })`: names, kinds, defaults, options, list sizes, a markup field's
Expand Down Expand Up @@ -2110,8 +2155,9 @@ to 3,000. Eight things the code does not say by itself:
out of the content. Both fields are still written, being hidden and required, and the runtime
ignores the first and works the second out again.

Not built: editing an existing package, layout for Drag and Drop and Crossword, and any judgement
of whether content is right, which stays the person's, in the verifier's preview.
Not built: editing an existing package, which a tool beside it does with `checkContent` as its
check; layout for Drag and Drop and Crossword; and any judgement of whether content is right, which
stays the person's, in the verifier's preview.

## The VS Code extension

Expand Down
32 changes: 28 additions & 4 deletions apps/skills/tests/author-verify.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
import { tmpdir } from 'node:os'
import { join, resolve } from 'node:path'
import { crc32, deflateSync } from 'node:zlib'
import { BlobReader, Uint8ArrayWriter, ZipReader } from '@zip.js/zip.js'
import { buildPackage, schemaOf } from '@missing-elements/h5p-author'
import { BlobReader, TextWriter, Uint8ArrayWriter, ZipReader, type FileEntry } from '@zip.js/zip.js'
import { buildPackage, checkContent, loadLibraries, packageLibraries, schemaOf } from '@missing-elements/h5p-author'
import { verifyPackage } from '@missing-elements/h5p-verify'
import { afterAll, beforeAll, describe, expect, it } from 'vitest'

Expand Down Expand Up @@ -105,15 +105,38 @@ async function playsBothWays(file: string) {
}
}

/**
* The check a tool that edits a saved package runs on what it writes (#107), on what a build wrote:
* the content its `h5p.json` names, against the libraries it carries, comes back with nothing
* reported and nothing changed.
*/
async function checksAsSaved(file: string) {
const reader = new ZipReader(new BlobReader(new Blob([await readFile(file)])))
try {
const entries = new Map((await reader.getEntries()).filter((entry) => !entry.directory).map((entry) => [entry.filename, entry as FileEntry]))
const files = { names: entries.keys(), read: (name: string) => entries.get(name)!.getData(new TextWriter()) }
const manifest = JSON.parse(await files.read('h5p.json'))
const params = JSON.parse(await files.read('content/content.json'))
const main = manifest.preloadedDependencies.find((dependency: { machineName: string }) => dependency.machineName === manifest.mainLibrary)
const content = { type: `${main.machineName} ${main.majorVersion}.${main.minorVersion}`, language: manifest.language, params }
const checked = checkContent(await loadLibraries(await packageLibraries(files), content), content)
expect([checked.problems, checked.notes]).toEqual([[], []])
expect(checked.params).toEqual(params)
} finally {
await reader.close()
}
}

describe.concurrent('every type file', () => {
it.each(files)('%s: its example builds, and plays trusted and untrusted without warnings', async (file) => {
it.each(files)('%s: its example builds, checks as saved content unchanged, and plays trusted and untrusted without warnings', async (file) => {
const source = await exampleOf(file)
const folder = join(dir, file.slice(0, -'.md'.length))
await mkdir(folder, { recursive: true })
for (const path of paths(source.params)) if (!/^https?:/.test(path)) await writeFile(join(folder, path), sample(path))
const output = join(folder, 'example.h5p')
const result = await buildPackage(source, output, { base: folder })
expect(result.notes).toEqual([])
await checksAsSaved(output)
await playsBothWays(output)
}, 180_000)

Expand All @@ -138,9 +161,10 @@ describe.concurrent('the quiz format', () => {
questions: example.questions.map((question: { title: string }) => ({ ...question, title: `${question.title}'s "draft" <b> & co` }))
}]
]
it.each(quizzes)('%s plays trusted and untrusted without warnings', async (name, source) => {
it.each(quizzes)('%s checks as saved content unchanged, and plays trusted and untrusted without warnings', async (name, source) => {
const output = join(dir, `${name.replaceAll(' ', '-')}.h5p`)
await buildPackage(source, output)
await checksAsSaved(output)
await playsBothWays(output)
}, 180_000)
})
43 changes: 38 additions & 5 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,16 +139,49 @@ try {
loads what the content brings in: the content type, every library its parameters name and each
library field's default, with their semantics in the language and marked as the layouts need them.
`entries` is the map `ContentGenerator` takes, every other library of the pack in it without its
semantics. It takes any object with `libraries`, `newest`, `open` and `translation`, such as one
over a package's own library folders. `markupText(value, field, report)`, `plainText(value, note)`
and `allowedTags(field)` are the build's rules for one text value against its field. What a type's
editor widget sets, and the check of a source, are the build's own and not exported.
semantics. It takes any object with `libraries`, `newest`, `open` and `translation`.
`markupText(value, field, report)`, `plainText(value, note)` and `allowedTags(field)` are the
build's rules for one text value against its field.

A tool that changes a saved package checks what it is about to write with the check the build runs
last on what it writes:

```js
import { checkContent, loadLibraries, openPack, packageLibraries } from '@missing-elements/h5p-author'

// `names`, the package's entry names; `read(name)`, an entry's text: from zip.js, or any reader.
const manifest = JSON.parse(await read('h5p.json'))
const main = manifest.preloadedDependencies.find((each) => each.machineName === manifest.mainLibrary)
const params = edited(JSON.parse(await read('content/content.json')))
const content = { type: `${main.machineName} ${main.majorVersion}.${main.minorVersion}`, language: manifest.language, params }
const pack = await openPack()
try {
const libraries = await loadLibraries(await packageLibraries({ names, read }, pack), content)
const { params: checked, problems, notes } = checkContent(libraries, content)
} finally {
await pack.close()
}
```

`packageLibraries(files, pack)` serves the package's own libraries where it carries a major of one,
and the pack's for the rest: content is in the shape of the version it was saved with. `checkContent`
checks every value against its field, as the build does, and takes what H5P saves as it is: files and
sub-content metadata, held to what the platforms keep of them, and each part's `subContentId`, which
the core names the part's statements by, so a learner's record stays the part's after an edit; a part
without one, or with another part's, gets a new one. It places what nobody placed and checks what a
content type's editor would, as the build does, and returns the content as checked with `problems`
and `notes`, each `{ path, message }`. Where the content names an older minor of a library than the
one it is checked against, a field only that minor has is a note: the player upgrades such content as
it plays. Content saved by the platforms can hold what their editor let an author save and the build
does not, such as a required text left empty; a tool that changes one part keeps the problems under
the paths it changed.

## What it does not do

It checks structure, not pedagogy: whether the answers are right, the questions fair, or the
pictures placed well is for a person to judge, in
[h5p-verify](https://www.npmjs.com/package/@missing-elements/h5p-verify)'s `--preview`. It does not
edit an existing package. The licence of each library is in the pack's `libraries.txt`.
edit an existing package itself: `checkContent` is the check for a tool that does. The licence of
each library is in the pack's `libraries.txt`.

MIT.
Loading
Loading