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
8 changes: 8 additions & 0 deletions design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,14 @@ text to the content check's rules, and `apps/skills` plays every example untrust
`installOnly` parts the `pack` export leaves out; a page gives
`@missing-elements/h5p-libraries/install`'s, and a build from a pack without them is refused,
naming the first library and where the full pack is.
- **A build says the H5P core a site needs** (#245). The upload check also refuses a package if
a library in it asks for a newer `coreApi` than the site's core, and its message names that
library. With pack 1.1.0, 50 of the 57 runnable libraries need 1.28: 31 ask for it themselves,
and the rest carry a library that does, such as H5P.JoubelUI 1.3 or H5P.Question 1.5. As checked
on 2026-11-19, Moodle has 1.28 from 4.5.11, 5.0.7 and 5.1.4 (2026-04-16), and the WordPress
plugin from 1.17. `coreApiOf` takes the newest over the parts a package carries. A build from
the command line (not `build --check`, which writes no package) and `h5p_build` print
`coreApiLine`, which names those releases for 1.28 and only the version for any other.
- **Where `npx` cannot install, a page builds.** ChatGPT's sandbox reaches npm only through
OpenAI's mirror, which refuses or hangs, and nothing in the skill can fix that. So the skill
hands over the source for the build page, `https://missing-elements.github.io/h5p/build/`,
Expand Down
3 changes: 2 additions & 1 deletion design/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ server, for ChatGPT or Claude on the web, is #210 and not this.
so builds at once take names of their own. The answer names the path written. Beside the package
goes its source, `<name>.source.json`, which the build page opens to change and build again; it
is made new, never written over or through a link, and where it cannot be, the answer says so.
- **A build answers with the content, the check and a picture.** The build's line, its notes, the
- **A build answers with the content, the check and a picture.** The build's line, the H5P core a
site needs (`coreApiLine`), its notes, the
outline (80 lines at most) and, with `verify`, the default, the verifier's summary of a check run
in a temporary folder, with its screenshot as an image. Where neither Chrome, Edge nor
Playwright's Chromium is found, the answer says "Not verified" and why. A source with problems
Expand Down
13 changes: 9 additions & 4 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,18 @@ npx @missing-elements/h5p-author@latest build rivers.json rivers.h5p

```
Built /work/rivers.h5p: H5P.Blanks, 9 libraries from the library pack 1.1.0, 3 more for installing on an H5P site.
Needs H5P core 1.28 or newer on a site it is uploaded to: Moodle 4.5.11, 5.0.7 or 5.1.4 and later, or the WordPress H5P plugin 1.17 and later. An older site refuses it.
H5P.Blanks 1.14: interface texts from its translation language/de.json.
Not verified: run npx @missing-elements/h5p-verify@latest on it and look at its screenshot before handing it over.
```

The package plays in the player and carries the editor libraries an H5P site's upload check asks
for, which the player never reads: a Moodle 4.5 with no library installed accepts
for, which the player never reads: a Moodle 4.5.15 with no library installed accepts
every type's example (Moodle was the one site tried; WordPress and Drupal run the same check). A
Question Set gains 120 kB by them; a Course Presentation or a Branching Scenario several MB, as
the same package exported from Moodle has, because their editors bring every type they can hold.
A site also refuses a package if a library in it asks for a newer H5P core than the site has. The
build's second line says which core that is: with pack 1.1.0, 1.28 for nearly every type.

It is written for an AI agent and its tokens: the agent writes what only an author can know, and
code writes everything that can be derived. The
Expand Down Expand Up @@ -208,7 +211,7 @@ Set's 2.6 MB, a container's up to 8.4 MB. `--all <folder>` writes one per conten
```js
import { buildPackage, schemaOf, SourceError } from '@missing-elements/h5p-author'

const { output, manifest, content, libraries, install, translations, notes, media, outline } =
const { output, manifest, content, libraries, install, coreApi, translations, notes, media, outline } =
await buildPackage(source, 'rivers.h5p', { base: process.cwd() })
```

Expand Down Expand Up @@ -248,7 +251,9 @@ not come back as it is, each `{ path, message }`. With `within`, the package and
inside those folders, on their real paths.

A result's `libraries` are the folders the package
plays with, `install` those carried for an H5P site's upload check. `missingForInstall(libraries)`
plays with, `install` those carried for an H5P site's upload check, and `coreApi` the newest H5P
core they ask for, `{ majorVersion, minorVersion }`, which a site needs to take the package;
`coreApiLine(coreApi)` says it as the command line does. `missingForInstall(libraries)`
is that check, over a package's `library.json` files: what a site with no library installed would
refuse it for, empty for a build. `schemaOf(machineName, { markdown, all,
libraries })` returns the field list. `writeBundle(type, output, { libraries })` and
Expand Down Expand Up @@ -351,7 +356,7 @@ const { blob, notes } = await buildPackage(source, { libraries, files: { 'volga.
Each part is fetched whole when a build first needs it, and checked against the index's SHA-256,
as in Node. `close()` the pack when the page is done with it.
- `buildPackage(source, { libraries, files, fetch })` throws a `SourceError` as in Node, and returns
`{ blob, manifest, content, libraries, install, translations, notes, media }`, as in Node. Its options:
`{ blob, manifest, content, libraries, install, coreApi, translations, notes, media }`, as in Node. Its options:
- `libraries`: a pack `openPack` opened, or what to open one from for this build alone.
- `files`: an object or a `Map` of the files a source names, by the names it gives them:
`{ "path": "volga.png" }` takes `files['volga.png']`.
Expand Down
3 changes: 2 additions & 1 deletion packages/author/bin/h5p-author.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
import { readFile } from 'node:fs/promises'
import { dirname, relative, resolve } from 'node:path'
import { parseArgs } from 'node:util'
import { buildPackage, readPackage, schemaOf, SourceError, writeBundle, writeBundles } from '../lib/author.mjs'
import { buildPackage, coreApiLine, readPackage, schemaOf, SourceError, writeBundle, writeBundles } from '../lib/author.mjs'
import { packVersion } from '../lib/node.mjs'

const USAGE = `Usage:
Expand Down Expand Up @@ -103,6 +103,7 @@ try {
const from = flags.libraries ? `the pack in ${flags.libraries}` : `the library pack ${await packVersion()}`
const install = result.install.length ? `, ${result.install.length} more for installing on an H5P site` : ''
console.log(`${check ? 'Checked, no package written' : `Built ${result.output}`}: ${result.manifest.mainLibrary}, ${result.libraries.length} libraries from ${from}${install}${result.media.length ? `, ${result.media.length} media file${result.media.length === 1 ? '' : 's'}` : ''}.`)
if (!check) console.log(coreApiLine(result.coreApi))
const language = String(result.manifest.language)
if (!/^en(?:-|$)/i.test(language)) {
for (const { library, translation, strings, english } of result.translations) {
Expand Down
8 changes: 5 additions & 3 deletions packages/author/lib/browser.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,11 @@ export * from './core.mjs'
* library with its part's URL
* @typedef {{
* blob: Blob, manifest: Record<string, unknown>, content: Record<string, unknown>, libraries: string[], install: string[],
* translations: import('./translate.mjs').TranslationReport[], notes: import('./build.mjs').Problem[], media: string[], outline: string
* coreApi: import('./install.mjs').CoreApi, translations: import('./translate.mjs').TranslationReport[], notes: import('./build.mjs').Problem[], media: string[], outline: string
* }} BuildResult the package, and what is worth telling about it: `libraries`, the folders it plays
* with; `install`, those it carries for an H5P site's upload check; `outline`, the content as text
* for a review (`outlineOf`)
* with; `install`, those it carries for an H5P site's upload check; `coreApi`, the newest H5P core
* they ask for, which a site needs to take the package (`coreApiLine` says it); `outline`, the
* content as text for a review (`outlineOf`)
* @typedef {{ libraries: Pack | PackIndex | string | URL, files?: Map<string, Blob> | Record<string, Blob>, fetch?: typeof fetch }} BuildOptions
* `libraries`, a pack `openPack` opened, which a page keeps for its builds, or what to open one
* from; `files`, the files a source names, by the names it gives them; `fetch`, for media named by
Expand Down Expand Up @@ -177,6 +178,7 @@ export async function buildPackage(input, options) {
content: built.content,
libraries: [...built.selected.keys()],
install: [...built.install.keys()],
coreApi: built.coreApi,
translations: built.translations,
notes: built.notes,
media: media.files.map((item) => item.name),
Expand Down
8 changes: 5 additions & 3 deletions packages/author/lib/build.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { TextReader } from '@zip.js/zip.js'
import { librariesNamedIn, planPack } from '@missing-elements/h5p-offline-player/plan'
import { checkContent, layoutContext, valueAt } from './check.mjs'
import { ContentGenerator, libraryString } from './generator.mjs'
import { installClosure } from './install.mjs'
import { coreApiOf, installClosure } from './install.mjs'
import { loadLibraries } from './libraries.mjs'
import { CC_VERSIONS } from './metadata.mjs'
import { machineNameOf, NAMING_KEYS, namingKey, nearestNames } from './names.mjs'
Expand Down Expand Up @@ -244,8 +244,9 @@ async function closure(pack, main, content) {
* @param {import('./media.mjs').MediaStore<F>} media
* @param {Problem[]} [said] the problems `sourceOf` found in the source's own fields, which come
* first among the content's: all of them in one round (#174)
* @returns {Promise<{ manifest: Record<string, unknown>, content: Record<string, unknown>, selected: Map<string, import('./pack.mjs').PartLibrary>, install: Map<string, import('./pack.mjs').PartLibrary>, translations: TranslationReport[], notes: Problem[], outline: string }>}
* `selected`, the libraries the package plays with; `install`, those an H5P site's upload check wants with them; `outline`, the
* @returns {Promise<{ manifest: Record<string, unknown>, content: Record<string, unknown>, selected: Map<string, import('./pack.mjs').PartLibrary>, install: Map<string, import('./pack.mjs').PartLibrary>, coreApi: import('./install.mjs').CoreApi, translations: TranslationReport[], notes: Problem[], outline: string }>}
* `selected`, the libraries the package plays with; `install`, those an H5P site's upload check wants with them; `coreApi`, the
* newest H5P core any of them asks for (`coreApiOf`); `outline`, the
* content as text for a review (`outlineOf`), made when it is first read
* @internal
*/
Expand Down Expand Up @@ -352,6 +353,7 @@ export async function composePackage(source, pack, media, said = []) {
let outline
return {
manifest, content, selected, install, translations, notes,
coreApi: coreApiOf([...selected.values(), ...install.values()].map((part) => part.library)),
// Made when it is first read: it is for a review, which only some callers make, and a build
// that never reads it never runs it.
get outline() { return (outline ??= outlineOf({ entries, main: mainLibrary }, { params: content })) }
Expand Down
3 changes: 2 additions & 1 deletion packages/author/lib/core.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ export { bundleLibraries, contentTypes } from './bundle.mjs'
export { checkContent } from './check.mjs'
export { outlineOf } from './outline.mjs'
export { ContentGenerator, librariesIn, libraryString } from './generator.mjs'
export { missingForInstall } from './install.mjs'
export { coreApiLine, coreApiOf, missingForInstall } from './install.mjs'
export { loadLibraries, packageLibraries } from './libraries.mjs'
export { sourceType } from './names.mjs'
export { GENERATED_END, GENERATED_START } from './schema.mjs'
Expand All @@ -22,6 +22,7 @@ export { allowedTags, editorWidget, markupText, plainText, takesMarkup } from '.
/**
* @typedef {import('./build.mjs').Source} Source
* @typedef {import('./check.mjs').CheckedContent} CheckedContent
* @typedef {import('./install.mjs').CoreApi} CoreApi
* @typedef {import('./generator.mjs').GeneratorOptions} GeneratorOptions
* @typedef {import('./generator.mjs').PackEntry} PackEntry
* @typedef {import('./libraries.mjs').LibraryRecord} LibraryRecord
Expand Down
41 changes: 41 additions & 0 deletions packages/author/lib/install.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -70,3 +70,44 @@ export function missingForInstall(libraries) {
}
return missing
}

/**
* The newest H5P core API that `libraries`, each given as its `library.json`, ask for in
* `coreApi`; one that asks for none asks for 1.0, as H5P reads it. H5P core's upload check
* (`H5PValidator::isValidH5pData`) refuses a package that carries a library asking for a newer core
* than the site has, and its message names that library, not the package.
* @param {Iterable<any>} libraries
* @returns {CoreApi}
*/
export function coreApiOf(libraries) {
let newest = { majorVersion: 1, minorVersion: 0 }
for (const library of libraries) {
const asked = library?.coreApi
if (!asked) continue
// A minor left out is 0; a version that is not two whole numbers is none.
const major = Number(asked.majorVersion)
const minor = Number(asked.minorVersion ?? 0)
if (!Number.isInteger(major) || !Number.isInteger(minor)) continue
if (major > newest.majorVersion || (major === newest.majorVersion && minor > newest.minorVersion)) newest = { majorVersion: major, minorVersion: minor }
}
return newest
}

/**
* The platforms' first releases with a core, by its version, as checked on 2026-11-19 (#245):
* Moodle's `h5plib_v128` (MDL-88092) and the WordPress plugin's bundled core. A version not here
* is said without them.
*/
const CORE_RELEASES = new Map([['1.28', 'Moodle 4.5.11, 5.0.7 or 5.1.4 and later, or the WordPress H5P plugin 1.17 and later']])

/**
* The line a build says of the core a site needs to take its package (`coreApiOf`).
* @param {CoreApi} core
*/
export function coreApiLine(core) {
const version = `${core.majorVersion}.${core.minorVersion}`
const releases = CORE_RELEASES.get(version)
return `Needs H5P core ${version} or newer on a site it is uploaded to${releases ? `: ${releases}` : ''}. An older site refuses it.`
}

/** @typedef {{ majorVersion: number, minorVersion: number }} CoreApi a core API version, as a `library.json` names one */
9 changes: 6 additions & 3 deletions packages/author/lib/node.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,11 @@ import { SourceError } from './source-error.mjs'
* @typedef {import('./translate.mjs').TranslationReport} TranslationReport
* @typedef {{
* output: string, manifest: Record<string, unknown>, content: Record<string, unknown>,
* libraries: string[], install: string[], translations: TranslationReport[], notes: Problem[], media: string[], outline: string
* libraries: string[], install: string[], coreApi: import('./install.mjs').CoreApi, translations: TranslationReport[], notes: Problem[], media: string[], outline: string
* }} BuildResult what was written, and what is worth telling about it: `libraries`, the folders the
* package plays with; `install`, those carried for an H5P site's upload check; `outline`, the
* content as text for a review (`outlineOf`)
* package plays with; `install`, those carried for an H5P site's upload check; `coreApi`, the
* newest H5P core they ask for, which a site needs to take the package (`coreApiLine` says it);
* `outline`, the content as text for a review (`outlineOf`)
* @typedef {{ libraries?: string, base?: string, fetch?: typeof fetch, within?: string[], check?: boolean }} BuildOptions
* `libraries`, a library pack's parts folder in place of the pinned pack; `base`, the folder a
* source's file paths are read from; `fetch`, for media named by web address; `within`, the
Expand Down Expand Up @@ -393,6 +394,7 @@ export async function buildPackage(input, output, options = {}) {
content: built.content,
libraries: [...built.selected.keys()],
install: [...built.install.keys()],
coreApi: built.coreApi,
translations: built.translations,
notes: built.notes,
media: media.files.map((item) => item.name),
Expand Down Expand Up @@ -430,6 +432,7 @@ export async function buildPackage(input, output, options = {}) {
content: built.content,
libraries: [...built.selected.keys()],
install: [...built.install.keys()],
coreApi: built.coreApi,
translations: built.translations,
notes: built.notes,
media: media.files.map((item) => item.name),
Expand Down
19 changes: 17 additions & 2 deletions packages/author/tests/build.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import { BlobReader, TextWriter, Uint8ArrayWriter, ZipReader } from '@zip.js/zip
import { pack } from '@missing-elements/h5p-libraries'
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { toJSONSchema } from 'zod/mini'
import { buildPackage, librariesIn, missingForInstall, SourceError, sourceSchema } from '../lib/author.mjs'
import { buildPackage, coreApiLine, coreApiOf, librariesIn, missingForInstall, SourceError, sourceSchema } from '../lib/author.mjs'
import { readSource } from '../lib/build.mjs'
import { LICENSES } from '../lib/metadata.mjs'
import { MediaStore } from '../lib/media.mjs'
Expand Down Expand Up @@ -177,6 +177,21 @@ describe('the quiz format', () => {
}
})

it('says the newest H5P core a library it carries asks for, which a site needs to take it (#245)', async () => {
const built = await build(example)
const asked = [...built.files].filter(([name]) => /^[^/]+\/library\.json$/.test(name)).map(([, text]) => JSON.parse(text).coreApi)
const [newest] = asked.filter(Boolean).map(({ majorVersion, minorVersion }) => [Number(majorVersion), Number(minorVersion)]).sort((a, b) => b[0] - a[0] || b[1] - a[1])
expect(built.coreApi).toEqual({ majorVersion: newest[0], minorVersion: newest[1] })
// H5P reads a library that names none as asking for 1.0; library.json may write the numbers as strings.
expect(coreApiOf([])).toEqual({ majorVersion: 1, minorVersion: 0 })
expect(coreApiOf([{ coreApi: { majorVersion: '1', minorVersion: '27' } }, { coreApi: { majorVersion: 1, minorVersion: 9 } }, {}])).toEqual({ majorVersion: 1, minorVersion: 27 })
// A minor left out is 0, and what is not two whole numbers is passed over: never "2.NaN".
expect(coreApiOf([{ coreApi: { majorVersion: 2 } }])).toEqual({ majorVersion: 2, minorVersion: 0 })
expect(coreApiOf([{ coreApi: { majorVersion: 2, minorVersion: 'x' } }, { coreApi: { majorVersion: 1.5, minorVersion: 1 } }])).toEqual({ majorVersion: 1, minorVersion: 0 })
expect(coreApiLine({ majorVersion: 1, minorVersion: 28 })).toBe('Needs H5P core 1.28 or newer on a site it is uploaded to: Moodle 4.5.11, 5.0.7 or 5.1.4 and later, or the WordPress H5P plugin 1.17 and later. An older site refuses it.')
expect(coreApiLine({ majorVersion: 1, minorVersion: 29 })).toBe('Needs H5P core 1.29 or newer on a site it is uploaded to. An older site refuses it.')
})

it('builds standalone Multiple Choice, escapes markup, and preserves false and zero values', async () => {
const source = {
...example, kind: 'multiple-choice', passPercentage: 0, passedFeedback: 'Done <b>& dusted</b>',
Expand Down Expand Up @@ -979,7 +994,7 @@ describe('the build', () => {
const project = await mkdtemp(join(dir, 'project-'))
await writeFile(join(project, 'german.json'), JSON.stringify({ ...example, language: 'de' }))
const german = await exec(process.execPath, [bin, 'build', 'german.json', 'german.h5p'], { cwd: project })
expect(german.stdout).toMatch(/^Built .*german\.h5p: H5P\.QuestionSet, \d+ libraries from the library pack \d+\.\d+\.\d+, \d+ more for installing on an H5P site\./)
expect(german.stdout).toMatch(/^Built .*german\.h5p: H5P\.QuestionSet, \d+ libraries from the library pack \d+\.\d+\.\d+, \d+ more for installing on an H5P site\.\nNeeds H5P core \d+\.\d+ or newer on a site it is uploaded to\b/)
expect(german.stdout).toMatch(/H5P\.MultiChoice 1\.\d+: interface texts from its translation language\/de\.json\./)
expect(german.stdout + german.stderr).toMatch(/H5P\.QuestionSet 1\.\d+: interface texts from its translation language\/de\.json/)
expect(german.stdout).toContain('Not verified')
Expand Down
Loading