diff --git a/design/author.md b/design/author.md index 3a0b49d4..01080c80 100644 --- a/design/author.md +++ b/design/author.md @@ -212,7 +212,9 @@ to 3,000. Eleven things the code does not say by itself: 98 rules resolve alike); and two comments said the editor sets what it does not, a Branching Question's own `nextContentId`, which it deletes, and a Game Map stage's `type`, which it keeps 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. + ignores the first and works the second out again. One departure since (#162): a multiple of a + fractional step is taken within a rounding error, where the editor's `%` refuses 0.3 in steps + of 0.1; no library in the pack has such a step, and the content check checks none. - **A package installs on an H5P site** (2026-11-06, #146). H5P core's upload check wants every library a package carries to have its preloaded, dynamic and editor dependencies with it at the @@ -222,8 +224,9 @@ to 3,000. Eleven things the code does not say by itself: wants* in libraries.md has the measurement). The owner's call: always carry them, since a `.h5p` a fresh Moodle refuses is broken, and a platform's export is as big. `lib/install.mjs` walks from the selected parts over the pack's index at exact versions, through what each added library - names in turn (`installClosure`), and `writePackage` copies them after the content, where nothing - reads them as the package plays; `h5p.json` lists what plays, as the platforms' exports write it. + names in turn (`installClosure`), and `writePackage` copies them after the content and the media, + where nothing reads them as the package plays, in a page's build too (#162: it wrote them before + the media); `h5p.json` lists what plays, as the platforms' exports write it. A package with media then goes through the normalizer, told to write the run after the media (`last`, #148), so with or without media a host without `Range` boots before the run arrives; over one with `Range` the player's warm takes only what `h5p.json` declares, and so leaves the diff --git a/packages/author/README.md b/packages/author/README.md index bc7e0a9e..a21a39c0 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -110,7 +110,9 @@ An unknown name lists the pack's content types. ## Options -- `--libraries `: another copy of the pack's `parts/` folder, in place of the pinned one. +- `--libraries ` or `--libraries=`: another copy of the pack's `parts/` folder, in + place of the pinned one. +- `-h`, `--help`; `-v`, `--version`: this package's version and the pack's. ## API @@ -211,13 +213,14 @@ 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, translations, notes, media }`. Its options: + `{ blob, manifest, content, libraries, install, 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']`. - `fetch`: for media named by web address. -- Media go in last and stored, each with its size and CRC in the header in front of it, as the player - reads them on a host without `Range`. An mp4 goes in as it was given. Moving its index to the +- Media go in after the content and stored, each with its size and CRC in the header in front of + it, as the player reads them on a host without `Range`; the libraries carried for an H5P site's + upload check come after them, as in Node. An mp4 goes in as it was given. Moving its index to the front, so that it starts before the whole file has arrived, is the normalizer's job, which runs in Node: `npx @missing-elements/h5p-normalize@latest course.h5p`. diff --git a/packages/author/bin/h5p-author.mjs b/packages/author/bin/h5p-author.mjs index 5ce5e0eb..bb1dad59 100755 --- a/packages/author/bin/h5p-author.mjs +++ b/packages/author/bin/h5p-author.mjs @@ -1,6 +1,7 @@ #!/usr/bin/env node import { readFile } from 'node:fs/promises' import { dirname, resolve } from 'node:path' +import { parseArgs } from 'node:util' import { buildPackage, schemaOf, SourceError } from '../lib/author.mjs' import { packVersion } from '../lib/node.mjs' @@ -14,26 +15,34 @@ build Makes a playable .h5p from a source: { "type", "title", "language", "lic schema Prints a content type's fields as a source writes them: --markdown as a skill's type file carries them, --all with the interface texts. +-h, --help show this +-v, --version print this package's version and the pack's + The libraries come from the pack this release pins (@missing-elements/h5p-libraries); --libraries names another copy's parts/ folder. Check every package with npx @missing-elements/h5p-verify@latest before handing it over.` -/** @param {string[]} argv */ +/** + * The command line as the verifier's and embed's read theirs: `--libraries dir` or + * `--libraries=dir`, and `-h`, `-v`. Which flags a command takes is checked after. + * @param {string[]} argv + */ function parse(argv) { - /** @type {string[]} */ - const positional = [] + const { values, positionals } = parseArgs({ + args: argv, + allowPositionals: true, + options: { + libraries: { type: 'string' }, + markdown: { type: 'boolean' }, + all: { type: 'boolean' }, + help: { type: 'boolean', short: 'h' }, + version: { type: 'boolean', short: 'v' } + } + }) /** @type {Record} */ const flags = {} - for (let i = 0; i < argv.length; i++) { - const arg = argv[i] - if (arg === '--libraries') { - const value = argv[++i] - if (!value || value.startsWith('--')) throw new Error('--libraries needs a folder') - flags.libraries = value - } else if (arg.startsWith('--')) flags[arg.slice(2)] = true - else positional.push(arg) - } - return { positional, flags } + for (const [name, value] of Object.entries(values)) if (value !== undefined && value !== false) flags[name] = value + return { positional: positionals, flags } } try { diff --git a/packages/author/lib/browser.mjs b/packages/author/lib/browser.mjs index b755ad0b..7fb0836a 100644 --- a/packages/author/lib/browser.mjs +++ b/packages/author/lib/browser.mjs @@ -14,7 +14,8 @@ export * from './core.mjs' * index's SHA-256; a source's files are `File`s or `Blob`s the page was given, by name; and the * package comes back as a `Blob`, its media stored with their sizes and CRC in their local headers, * as embed's SCORM writer stores its entries since #92, so that the player reads each one's size - * off its header on a host without `Range`. An mp4 goes in as it was given: moving its index to + * off its header on a host without `Range`, and before the libraries carried for an H5P site's + * upload check, as Node's build lays them out. An mp4 goes in as it was given: moving its index to * the front is the normalizer's, which runs in Node. It needs a secure context, https, localhost or * a Tauri window, for `crypto.subtle` and `crypto.randomUUID`. */ @@ -24,9 +25,10 @@ export * from './core.mjs' * the `pack` export of `@missing-elements/h5p-libraries` as a bundler emits it: the index, each * library with its part's URL * @typedef {{ - * blob: Blob, manifest: Record, content: Record, libraries: string[], + * blob: Blob, manifest: Record, content: Record, libraries: string[], install: string[], * translations: import('./translate.mjs').TranslationReport[], notes: import('./build.mjs').Problem[], media: string[] - * }} BuildResult the package, and what is worth telling about it + * }} 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 * @typedef {{ libraries: Pack | PackIndex | string | URL, files?: Map | Record, 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 @@ -158,16 +160,18 @@ export async function buildPackage(input, options) { const media = new MediaStore(pageMedia(files), { fetch: fetchImpl }) const built = await composePackage(source, pack, media) const writer = new ZipWriter(new BlobWriter('application/zip'), { useWebWorkers: false }) - await writePackage(writer, built, pack) - for (const item of media.files) { - // Stored, its size and CRC in its local header: written into a stream, zip.js would put them in a descriptor after it. - await writer.add(`content/${item.name}`, new BlobReader(item.from), { passThrough: true, compressionMethod: 0, uncompressedSize: item.from.size, crc32: await crcOf(item.from) }) - } + await writePackage(writer, built, pack, async () => { + for (const item of media.files) { + // Stored, its size and CRC in its local header: written into a stream, zip.js would put them in a descriptor after it. + await writer.add(`content/${item.name}`, new BlobReader(item.from), { passThrough: true, compressionMethod: 0, uncompressedSize: item.from.size, crc32: await crcOf(item.from) }) + } + }) return { blob: await writer.close(), manifest: built.manifest, content: built.content, libraries: [...built.selected.keys()], + install: [...built.install.keys()], translations: built.translations, notes: built.notes, media: media.files.map((item) => item.name) diff --git a/packages/author/lib/build.mjs b/packages/author/lib/build.mjs index ad9e0503..78923f80 100644 --- a/packages/author/lib/build.mjs +++ b/packages/author/lib/build.mjs @@ -52,7 +52,11 @@ export function readSource(input) { if (!isObject(input)) throw new SourceError([{ path: 'source', message: 'expected an object: { "type", "title", "language", "license", "authors", "params" }' }]) const known = ['type', 'title', 'language', 'license', 'licenseVersion', 'authors', 'source', 'yearFrom', 'yearTo', 'params'] for (const key of Object.keys(input)) if (!known.includes(key)) report(key, `is not a field of a source; the fields are ${known.join(', ')}`) - if (typeof input.type !== 'string' || !/^\S+$/.test(input.type.trim())) report('type', 'expected a content type\'s machine name, such as "H5P.Blanks"') + if (typeof input.type === 'string' && /^\S+\s+\d+\.\d+$/.test(input.type.trim())) { + // checkContent takes a version, as saved content names one; a build takes the pack's newest. + const [name] = input.type.trim().split(/\s/) + report('type', `takes the machine name alone, "${name}": the version is the pack's newest`) + } else if (typeof input.type !== 'string' || !/^\S+$/.test(input.type.trim())) report('type', 'expected a content type\'s machine name, such as "H5P.Blanks"') if (typeof input.title !== 'string' || !input.title.trim()) report('title', 'expected the activity\'s title') else if (input.title.length > 255) report('title', 'takes at most 255 characters') if (typeof input.language !== 'string') report('language', 'expected a BCP 47 language tag, such as "en" or "de-AT"') @@ -223,21 +227,24 @@ export async function composePackage(source, pack, media) { /** * What a package holds but its media, in the order a package streams in: its manifest, the - * libraries it plays with, each part's own files copied as they are, the content, then the - * libraries an H5P site's upload check wants, which nothing reads as the package plays, so the - * frame boots before they arrive on a host without `Range`. The caller adds the media after it, - * last, and in Node has the normalizer keep those libraries after the media (`last`). + * libraries it plays with, each part's own files copied as they are, the content, the media + * `media` writes, then the libraries an H5P site's upload check wants, which nothing reads as the + * package plays: on a host without `Range` the frame boots and the media arrive before them. A + * page's build writes the package once, so the order is this one; Node's has the normalizer keep + * it (`last`) as it moves an mp4's index first. * @param {import('@zip.js/zip.js').ZipWriter} writer * @param {{ manifest: Record, content: Record, selected: Map, install: Map }} built * @param {import('./pack.mjs').Pack} pack + * @param {() => Promise} media adds the media to `writer` * @internal */ -export async function writePackage(writer, { manifest, content, selected, install }, pack) { +export async function writePackage(writer, { manifest, content, selected, install }, pack, media) { /** @param {import('./pack.mjs').PartLibrary} part */ const copy = (part) => writer.appendZip(pack.archiveOf(part), { filter: (entry) => !entry.directory && entry.filename.startsWith(`${part.folder}/`) }) await writer.add('h5p.json', new TextReader(JSON.stringify(manifest))) for (const part of selected.values()) await copy(part) await writer.add('content/content.json', new TextReader(JSON.stringify(content))) + await media() for (const part of install.values()) await copy(part) } diff --git a/packages/author/lib/generator.mjs b/packages/author/lib/generator.mjs index 341fa6f0..12778cda 100644 --- a/packages/author/lib/generator.mjs +++ b/packages/author/lib/generator.mjs @@ -288,7 +288,7 @@ export class ContentGenerator { } }) for (const [key, value] of Object.entries(given)) { - if (key in out || fields.some((field) => field.name === key)) continue + if (Object.hasOwn(out, key) || fields.some((field) => field.name === key)) continue // Lenient, what the semantics do not name is kept as written: the content check removes // it, which a sweep file may mean to test. if (this.lenient) { @@ -631,7 +631,10 @@ export class ContentGenerator { /** * A number as h5peditor-number.js checks it: within its range; with at most `decimals` * decimals, or none where the field has no `decimals` and no widget of its own draws it; and a - * multiple of `step`, counted from 0 as its `value % step` counts. + * multiple of `step`, counted from 0 as its `value % step` counts. Where it departs from the + * editor: a multiple of a fractional step is taken within a rounding error, where the editor's + * `%` refuses it (`0.3 % 0.1` is `0.0999…`); no library in the pack has a fractional step, and + * the content check checks none (packages/runtime/src/content-check.ts). * @param {any} field * @param {unknown} written * @param {string} path @@ -647,7 +650,14 @@ export class ContentGenerator { const factor = 10 ** Number(field.decimals) if (Math.round(written * factor) / factor !== written) this.report(path, `takes ${field.decimals ? `at most ${field.decimals} decimals` : 'a whole number'}`) } else if (!field.widget && !this.drawn.has(field) && !Number.isInteger(written)) this.report(path, 'takes a whole number') - if (field.step !== undefined && Number(field.step) > 0 && written % Number(field.step) !== 0) this.report(path, `takes steps of ${field.step}`) + const step = Number(field.step) + if (field.step !== undefined && step > 0) { + const steps = written / step + // The value, the step and their quotient are each rounded once, so the quotient is off by + // at most about 1.5 Number.EPSILON of itself; the bound is four. A share as loose as 1e-9 + // let 50000000.05 pass in steps of 0.1, half a step off. + if (Math.abs(steps - Math.round(steps)) > 4 * Number.EPSILON * Math.max(1, Math.abs(steps))) this.report(path, `takes steps of ${field.step}`) + } return written } diff --git a/packages/author/lib/media.mjs b/packages/author/lib/media.mjs index 5e4b2d10..d4a737fa 100644 --- a/packages/author/lib/media.mjs +++ b/packages/author/lib/media.mjs @@ -117,6 +117,19 @@ function extensionOf(name) { return dot > 0 ? name.slice(dot + 1).toLowerCase() : '' } +/** + * A URL's path decoded, or as written where an escape in it is not one, `%zz`: a name to keep, + * which nothing is gained by refusing. + * @param {string} path + */ +function decoded(path) { + try { + return decodeURIComponent(path) + } catch { + return path + } +} + /** * A path's last segment, past any slash it ends with, as Node's `basename` takes it. * @param {string} path @@ -176,7 +189,7 @@ export class MediaStore { this.idle = idle /** @type {StagedFile[]} */ this.files = [] - /** @type {Map} by source, so one file named twice is copied once */ + /** @type {Map} by kind and source, so one file named twice for one kind is copied once */ this.known = new Map() /** @type {Set} */ this.names = new Set() @@ -213,7 +226,8 @@ export class MediaStore { return { path: source, copyright } } const types = /** @type {Record} */ (TYPES[kind]) - let known = this.known.get(source) + const key = `${kind} ${source}` + let known = this.known.get(key) if (!known) { const staged = web ? await this.#download(source, kind, types, at, report) : await this.#local(source, types, at, report) if (!staged) return { path: source, copyright } @@ -233,7 +247,7 @@ export class MediaStore { } } this.files.push({ name, from: staged.from }) - this.known.set(source, described) + this.known.set(key, described) known = described } const { name, ...rest } = known @@ -278,7 +292,7 @@ export class MediaStore { async #local(source, types, at, report) { const name = this.access.name(source) const extension = extensionOf(name) - if (!(extension in types)) { + if (!Object.hasOwn(types, extension)) { report(`${at}.path`, `${source}: this field takes ${Object.keys(types).map((each) => `.${each}`).join(', ')}`) return null } @@ -336,7 +350,7 @@ export class MediaStore { } const named = extensionOf(lastSegment(new URL(response.url || url.href).pathname)) const served = (response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase() - const extension = named in types ? named : Object.keys(types).find((each) => types[each] === served) + const extension = Object.hasOwn(types, named) ? named : Object.keys(types).find((each) => types[each] === served) if (!extension) { await response.body.cancel() report(`${at}.path`, `${source} is ${served || 'of an unknown type'}: this field takes ${Object.keys(types).map((each) => `.${each}`).join(', ')}`) @@ -357,7 +371,7 @@ export class MediaStore { } catch (error) { return failed(error) } - const last = lastSegment(decodeURIComponent(new URL(response.url || url.href).pathname)) + const last = lastSegment(decoded(new URL(response.url || url.href).pathname)) const stem = (named && last.endsWith(`.${named}`) && last !== `.${named}` ? last.slice(0, -named.length - 1) : last) || kind return { from, extension, stem } } finally { diff --git a/packages/author/lib/node.mjs b/packages/author/lib/node.mjs index 5fd9c24f..2134e4ce 100644 --- a/packages/author/lib/node.mjs +++ b/packages/author/lib/node.mjs @@ -133,19 +133,20 @@ export async function buildPackage(input, output, options = {}) { const file = await open(staged, 'wx') try { const writer = new ZipWriter(Writable.toWeb(file.createWriteStream()), { useWebWorkers: false }) - await writePackage(writer, built, pack) - for (const item of media.files) { - await writer.add(`content/${item.name}`, /** @type {ReadableStream} */ (Readable.toWeb(createReadStream(item.from))), { level: 0 }) - } + await writePackage(writer, built, pack, async () => { + for (const item of media.files) { + await writer.add(`content/${item.name}`, /** @type {ReadableStream} */ (Readable.toWeb(createReadStream(item.from))), { level: 0 }) + } + }) await writer.close() } finally { await file.close() } let final = staged if (media.files.length) { - // Media stored and last, an mp4's index first: the layout a package streams in. The - // libraries carried for an H5P site's upload check go after the media, where `writePackage` - // put them after the content: a host that ignores `Range` then boots before they arrive. + // Media stored, an mp4's index first: the layout a package streams in. The libraries + // carried for an H5P site's upload check stay after the media, where `writePackage` put + // them: a host that ignores `Range` then boots, and plays the media, before they arrive. final = join(temporary, 'normalized.h5p') await normalizeArchive({ input: staged, output: final, last: [...built.install.keys()] }) } diff --git a/packages/author/lib/schema.mjs b/packages/author/lib/schema.mjs index 2579c6a4..1d10792b 100644 --- a/packages/author/lib/schema.mjs +++ b/packages/author/lib/schema.mjs @@ -200,6 +200,27 @@ export function schemaLines(semantics, options = {}) { export const GENERATED_START = '' export const GENERATED_END = '' +/** + * A type file with its generated section in place: between its markers, or appended to a file that + * has none. A file with one marker only, either twice, or the end before the start was edited by + * hand, and is refused: appending would leave the stale section behind, for good. + * @param {string} text + * @param {string} section + * @param {string} name + * @internal + */ +export function withSection(text, section, name) { + const count = (/** @type {string} */ marker) => text.split(marker).length - 1 + const [starts, ends] = [count(GENERATED_START), count(GENERATED_END)] + if (!starts && !ends) return `${text.trimEnd()}\n\n${section}\n` + const start = text.indexOf(GENERATED_START) + const end = text.indexOf(GENERATED_END) + if (starts !== 1 || ends !== 1 || end < start) { + throw new Error(`${name}: its generated section's markers are broken (${starts} start, ${ends} end${starts === 1 && ends === 1 ? ', the end first' : ''}); put back one of each, ${GENERATED_START} before ${GENERATED_END}, around the section`) + } + return `${text.slice(0, start)}${section}${text.slice(end + GENERATED_END.length)}` +} + /** * The generated section of a type file: the fields, under a heading, between markers that a * refresh rewrites. diff --git a/packages/author/scripts/sync-skill.mjs b/packages/author/scripts/sync-skill.mjs index d542968c..55115ee9 100644 --- a/packages/author/scripts/sync-skill.mjs +++ b/packages/author/scripts/sync-skill.mjs @@ -4,7 +4,8 @@ // weekly refresh does, and apps/skills' test fails when a file is out of date. import { readdir, readFile, writeFile } from 'node:fs/promises' import { join, resolve } from 'node:path' -import { GENERATED_END, GENERATED_START, schemaOf } from '../lib/author.mjs' +import { schemaOf } from '../lib/author.mjs' +import { withSection } from '../lib/schema.mjs' const folder = resolve(import.meta.dirname, '../../../skills/h5p-author/references/types') const check = process.argv.includes('--check') @@ -13,11 +14,7 @@ for (const name of (await readdir(folder)).filter((file) => file.endsWith('.md') const path = join(folder, name) const text = await readFile(path, 'utf8') const section = await schemaOf(name.slice(0, -'.md'.length), { markdown: true }) - const start = text.indexOf(GENERATED_START) - const end = text.indexOf(GENERATED_END) - const updated = start >= 0 && end > start - ? `${text.slice(0, start)}${section}${text.slice(end + GENERATED_END.length)}` - : `${text.trimEnd()}\n\n${section}\n` + const updated = withSection(text, section, name) if (updated === text) continue stale += 1 if (check) console.error(`${name} is out of date with the pack`) diff --git a/packages/author/tests/build.test.ts b/packages/author/tests/build.test.ts index 0d831747..5eaf48bc 100644 --- a/packages/author/tests/build.test.ts +++ b/packages/author/tests/build.test.ts @@ -281,6 +281,8 @@ describe('any content type in the pack', () => { it('lists every problem a source has at once, each by its path, and writes nothing', async () => { expect(await problems({ ...META, type: 'H5P.Nope', params: {} })).toEqual(['type: the library pack has no content type H5P.Nope']) + // A version is saved content's, which checkContent takes; a build plays the pack's newest (#162). + expect(await problems({ ...META, type: 'H5P.Blanks 1.14', params: {} })).toEqual(['type: takes the machine name alone, "H5P.Blanks": the version is the pack\'s newest']) expect(await problems({ ...META, license: 'MIT', authors: [{ name: 'A' }], extra: 1, type: 'H5P.Blanks' })).toEqual([ 'extra: is not a field of a source; the fields are type, title, language, license, licenseVersion, authors, source, yearFrom, yearTo, params', expect.stringMatching(/^license: use one of/), @@ -353,6 +355,7 @@ describe('media', () => { if (request.url === '/pictures/map.png') response.writeHead(200, { 'content-type': 'image/png' }).end(png(40, 20)) else if (request.url === '/picture') response.writeHead(200, { 'content-type': 'image/png' }).end(png(10, 30)) else if (request.url === '/page.html') response.writeHead(200, { 'content-type': 'text/html' }).end('

no

') + else if (request.url === '/odd%zz.png') response.writeHead(200, { 'content-type': 'image/png' }).end(png(20, 10)) else if (request.url === '/trickle.png') { // Slow, and never silent for long: eight pieces, 100 ms apart. const bytes = png(40, 30) @@ -487,8 +490,26 @@ describe('media', () => { expect(reported).toEqual([`params.silent.path: ${origin}/stalled.png could not be downloaded: nothing arrived for 0.3 s`]) }) + it('keeps a download whose address has an escape that is not one, under its name as written (#162)', async () => { + const reported: string[] = [] + const store = new MediaStore(nodeMedia({ base: dir, temporary: dir })) + expect(await store.resolve({ type: 'image' }, { path: `${origin}/odd%zz.png` }, 'params.odd', (path, message) => reported.push(`${path}: ${message}`))).toMatchObject({ path: 'images/odd-zz.png', width: 20, height: 10 }) + expect(reported).toEqual([]) + }) + + it('copies one file named in an image field and a file field once for each, as H5P keeps them apart (#162)', async () => { + await writeFile(join(dir, 'chart.png'), png(30, 20)) + const store = new MediaStore(nodeMedia({ base: dir, temporary: dir })) + const report = () => { throw new Error('no problem expected') } + expect(await store.resolve({ type: 'file' }, { path: 'chart.png' }, 'params.download', report)).toEqual({ path: 'files/chart.png', mime: 'image/png', copyright: { license: 'U' } }) + expect(await store.resolve({ type: 'image' }, { path: 'chart.png' }, 'params.picture', report)).toEqual({ path: 'images/chart.png', mime: 'image/png', width: 30, height: 20, copyright: { license: 'U' } }) + expect(await store.resolve({ type: 'image' }, { path: 'chart.png' }, 'params.again', report)).toMatchObject({ path: 'images/chart.png' }) + expect(store.files.map(({ name }) => name)).toEqual(['files/chart.png', 'images/chart.png']) + }) + it('names a file that is missing, of a type the field does not take, or not downloadable', async () => { await writeFile(join(dir, 'notes.txt'), 'x') + await writeFile(join(dir, 'x.constructor'), 'x') expect(await problems({ ...META, type: 'H5P.MemoryGame', @@ -498,7 +519,8 @@ describe('media', () => { { image: { path: 'notes.txt' }, imageAlt: 'b' }, { image: { path: `${origin}/gone.png` }, imageAlt: 'c' }, { image: { path: `${origin}/page.html` }, imageAlt: 'd' }, - { image: { path: 'ftp://example.org/a.png' }, imageAlt: 'e' } + { image: { path: 'ftp://example.org/a.png' }, imageAlt: 'e' }, + { image: { path: 'x.constructor' }, imageAlt: 'f' } ] } }, { base: dir })).toEqual([ @@ -506,7 +528,9 @@ describe('media', () => { 'params.cards[1].image.path: notes.txt: this field takes .png, .jpg, .jpeg, .gif, .bmp', `params.cards[2].image.path: ${origin}/gone.png answered 404`, `params.cards[3].image.path: ${origin}/page.html is text/html: this field takes .png, .jpg, .jpeg, .gif, .bmp`, - 'params.cards[4].image.path: expected a file beside the source or an http(s) address' + 'params.cards[4].image.path: expected a file beside the source or an http(s) address', + // A name an object's prototype has is no type (#162). + 'params.cards[5].image.path: x.constructor: this field takes .png, .jpg, .jpeg, .gif, .bmp' ]) }) }) @@ -563,6 +587,11 @@ describe('the build', () => { expect(schema).toMatch(/^H5P\.TrueFalse 1\.\d+: True\/False Question\n- `media` group/) expect(schema).toContain('- `correct` one of "true" | "false" = "true"') await expect(exec(process.execPath, [bin, 'schema', 'H5P.Nope'])).rejects.toMatchObject({ stderr: expect.stringContaining('H5P.Blanks (Fill in the Blanks)') }) + // --name=value, -h and -v, as the verifier and embed read them (#162). + expect((await exec(process.execPath, [bin, 'schema', 'H5P.TrueFalse', `--libraries=${parts}`])).stdout).toBe(schema) + expect((await exec(process.execPath, [bin, '-h'])).stdout).toMatch(/^Usage:\n {2}h5p-author build/) + expect((await exec(process.execPath, [bin, '-v'])).stdout).toMatch(/^@missing-elements\/h5p-author \d+\.\d+\.\d+, library pack \d+\.\d+\.\d+\n$/) + await expect(exec(process.execPath, [bin, 'build', 'a.json', 'a.h5p', '--markdown'])).rejects.toMatchObject({ code: 1, stderr: 'h5p-author: build does not take --markdown\n' }) }, 120_000) }) diff --git a/packages/author/tests/generator.test.ts b/packages/author/tests/generator.test.ts index 1d133781..02cf7348 100644 --- a/packages/author/tests/generator.test.ts +++ b/packages/author/tests/generator.test.ts @@ -167,6 +167,18 @@ describe('content authored from semantics', () => { expect(generate(semantics, { size: 3 }, [], STRICT).problems).toEqual([{ path: 'params.size', message: 'takes steps of 2' }]) }) + it('takes a multiple of a fractional step, which the editor\'s `%` misses by a rounding error (#162)', () => { + const semantics = [{ name: 'ratio', type: 'number', decimals: 2, step: 0.1 }] + for (const ratio of [0.3, 0.7, 2.3, 1234.5, 50000000.1]) expect(generate(semantics, { ratio }, [], STRICT).problems, String(ratio)).toEqual([]) + // Half a step off, however large: the bound is the arithmetic's error, not a share of the value. + for (const ratio of [0.35, 50000000.05]) expect(generate(semantics, { ratio }, [], STRICT).problems, String(ratio)).toEqual([{ path: 'params.ratio', message: 'takes steps of 0.1' }]) + }) + + it('takes a field named as an object\'s own properties are, toString or constructor, for what it is: not a field (#162)', () => { + const { problems } = generate([{ name: 'count', type: 'number', default: 1 }], JSON.parse('{ "toString": 1, "constructor": 2, "__proto__": 3 }'), [], STRICT) + expect(problems.map(({ path }) => path)).toEqual(['params.toString', 'params.constructor', 'params.__proto__']) + }) + it('stores plain text escaped and markup as the editor writes it, and refuses a tag the field does not take', () => { const { params, problems, notes } = generate([ { name: 'title', type: 'text' }, diff --git a/packages/author/tests/layout.test.ts b/packages/author/tests/layout.test.ts index 47d62189..a83a5520 100644 --- a/packages/author/tests/layout.test.ts +++ b/packages/author/tests/layout.test.ts @@ -4,7 +4,7 @@ import { join } from 'node:path' import { afterAll, beforeAll, describe, expect, it } from 'vitest' import { buildPackage, SourceError } from '../lib/author.mjs' import { imageSize } from '../lib/media.mjs' -import { GENERATED_END, GENERATED_START, schemaLines, schemaMarkdown } from '../lib/schema.mjs' +import { GENERATED_END, GENERATED_START, schemaLines, schemaMarkdown, withSection } from '../lib/schema.mjs' import { jpeg, png } from './helpers/media' const META = { title: 'Layout', language: 'en', license: 'U', authors: [{ name: 'Ann Author', role: 'Author' }] } @@ -261,6 +261,16 @@ describe('the schema a source is written from', () => { expect(schemaLines(semantics, { all: true }).lines).toContain(' - `check` text = "Check"') }) + it('puts a type file\'s section between its markers, or after a file with none, and refuses broken markers (#162)', () => { + const section = `${GENERATED_START}\n\nnew\n\n${GENERATED_END}` + const old = `${GENERATED_START}\n\nold\n\n${GENERATED_END}` + expect(withSection(`# Notes\n\n${old}\n`, section, 'T.md')).toBe(`# Notes\n\n${section}\n`) + expect(withSection('# Notes\n', section, 'T.md')).toBe(`# Notes\n\n${section}\n`) + expect(() => withSection(`# Notes\n\n${GENERATED_START}\n\nold\n`, section, 'T.md')).toThrow('T.md: its generated section\'s markers are broken (1 start, 0 end)') + expect(() => withSection(`# Notes\n\n${GENERATED_END}\nold\n${GENERATED_START}\n`, section, 'T.md')).toThrow('(1 start, 1 end, the end first)') + expect(() => withSection(`${old}\n${old}\n`, section, 'T.md')).toThrow('(2 start, 2 end)') + }) + it('writes a type file\'s generated section between its markers', () => { const markdown = schemaMarkdown({ machineName: 'H5P.Test', majorVersion: 1, minorVersion: 2 }, semantics) expect(markdown.startsWith(`${GENERATED_START}\n\n## Fields of H5P.Test 1.2\n`)).toBe(true) diff --git a/packages/author/tests/page.test.ts b/packages/author/tests/page.test.ts index 461e02ab..63ba9011 100644 --- a/packages/author/tests/page.test.ts +++ b/packages/author/tests/page.test.ts @@ -96,7 +96,7 @@ describe('the build in a page', () => { const page = await buildPackage(BLANKS, { libraries: opened }) const node = await buildInNode(BLANKS, join(dir, 'blanks.h5p')) expect(page.blob.type).toBe('application/zip') - expect([page.manifest, page.content, page.libraries, page.notes, page.media]).toEqual([node.manifest, node.content, node.libraries, node.notes, node.media]) + expect([page.manifest, page.content, page.libraries, page.install, page.notes, page.media]).toEqual([node.manifest, node.content, node.libraries, node.install, node.notes, node.media]) // Each file by its name and hash, in order: comparing the bytes themselves with toEqual takes seconds. const hashes = ({ files }: { files: Map }) => [...files].map(([name, bytes]) => [name, createHash('sha256').update(bytes).digest('hex')]) const fromPage = await archive(new Uint8Array(await page.blob.arrayBuffer())) @@ -104,7 +104,7 @@ describe('the build in a page', () => { expect(hashes(fromPage)).toEqual(hashes(fromNode)) }) - it('stores media last, with their size and CRC in their local headers, and describes them as H5P records them', async () => { + it('stores media after the content, with their size and CRC in their local headers, and describes them as H5P records them', async () => { const picture = png(480, 270) const result = await buildPackage(QUIZ, { libraries: opened, files: { 'volga.png': new File([new Uint8Array(picture)], 'IMG_0412.png') } }) expect(result.media).toEqual(['images/volga.png']) @@ -114,10 +114,17 @@ describe('the build in a page', () => { expect(question.params.media.type.params.file).toEqual({ path: 'images/volga.png', mime: 'image/png', width: 480, height: 270, copyright: { license: 'U' } }) const bytes = new Uint8Array(await result.blob.arrayBuffer()) const { files, entries } = await archive(bytes) - expect(entries.at(-1)!.filename).toBe('content/images/volga.png') + // After the content, before the libraries carried for an H5P site's upload check, as Node's + // build lays them out: on a host without Range the media arrive before them (#162). + const names = entries.map(({ filename }) => filename) + const at = names.indexOf('content/images/volga.png') + expect(result.install.length).toBeGreaterThan(0) + expect(names[at - 1]).toBe('content/content.json') + expect(names.slice(at + 1).every((name) => result.install.some((folder) => name.startsWith(`${folder}/`)))).toBe(true) + expect(names.slice(at + 1).length).toBeGreaterThan(0) expect(files.get('content/images/volga.png')).toEqual(new Uint8Array(picture)) // No data descriptor: the header says where the data ends. - expect(localHeader(bytes, entries.at(-1)!.offset)).toEqual({ signature: 0x04034b50, flags: 0, method: 0, crc32: crc32(picture), compressedSize: picture.length, size: picture.length }) + expect(localHeader(bytes, entries[at].offset)).toEqual({ signature: 0x04034b50, flags: 0, method: 0, crc32: crc32(picture), compressedSize: picture.length, size: picture.length }) }) it('takes the files from a Map too, and names one the source names that the page did not give', async () => { diff --git a/skills/h5p-author/SKILL.md b/skills/h5p-author/SKILL.md index 728f694b..1357995e 100644 --- a/skills/h5p-author/SKILL.md +++ b/skills/h5p-author/SKILL.md @@ -49,7 +49,9 @@ two that fit the material and objective, a sentence each on why, and wait for th Media come from the user; never invent them. For a type not listed, run `npx @missing-elements/h5p-author@latest schema ` and say it has no notes here. Never -read a library's semantics or code yourself. +read a library's semantics or code yourself: the type file and `schema` say what a source may +write, and an agent that works it out from the library spends two to three times as much for +the same package. ## 2. Write the source @@ -73,13 +75,19 @@ content holds have files too: H5P.AdvancedText, H5P.Image, H5P.Video, H5P.Text. ## 3. Build +Build in a working folder of your own, not in the folder the user named: + ```bash npx @missing-elements/h5p-author@latest build source.json course.h5p ``` -It writes nothing until the whole source is right, listing every problem by its path, and -never overwrites a file. Fix and build to a new name. Pass its notes on to the user: texts -left in English, a slide that holds too much. +A source with a problem writes nothing: the build lists every problem by its path, so fix them +all and run it again under the same name. Once a build has written its file it never writes +over it, so a later build takes a new name (`course-2.h5p`). Copy the one you hand over to the +name the user asked for without writing over a file already there (`cp -n`). If that name is +taken, ask, or where you cannot ask, take a new name and say so. Never delete or overwrite a file +to free a name. Pass the build's notes on to the user: texts left in English, a slide that holds +too much. ## 4. Verify @@ -87,9 +95,13 @@ left in English, a slide that holds too much. npx @missing-elements/h5p-verify@latest course.h5p ``` -Read `report.json` and look at `screenshot.png`: layout mistakes raise no error. Follow the -`h5p-verify` skill's loop if it is installed. Fix the source, never by removing what fails. -Without a browser, say the package is **unverified**. +It writes `course.verify/report.json` and `course.verify/screenshot.png` beside the package +(`--out ` puts them elsewhere). Read the report's `verdict`, `reasons`, `errors` and +`warnings`: a run that fails may say why only in `reasons`, such as content that never reached +ready or drew nothing. Look at the screenshot too: layout mistakes raise no error. One run is +enough: the build already writes what an H5P site's content check keeps, so `--untrusted` finds +nothing more. Follow the `h5p-verify` skill's loop if it is installed. Fix the source, never by +removing what fails. Without a browser, say the package is **unverified**. ## 5. Review and hand over @@ -100,15 +112,25 @@ npx @missing-elements/h5p-verify@latest course.h5p --preview ``` Run it in the background; it ends once its tab has closed. Ask the user to work through all of -it, wrong answers included; its Download button saves a copy. With browser tools of your own, -add `--no-open` and play the address yourself. Where the command does not run on the user's -computer, hand over the file and the command. - -Deliver the `.h5p`, the source, the report, screenshot and full `revision`, the preview -command, and any notes. A pass means it starts and draws, not that it is accurate, accessible -or right for every LMS. The package carries the editor libraries an H5P site's upload check asks -for, so a Moodle with no library installed accepts it (the one site tried). It carries H5P's libraries, each under its own licence, most -MIT, listed in the pack's [`libraries.txt`](https://github.com/missing-elements/h5p-offline-player/blob/main/packages/libraries/libraries.txt): -tell the user, so they check those terms before they distribute it. The H5P Preview extension (`MissingElements.h5p-preview`) plays it in -VS Code, Cursor or VSCodium; `h5p-player-setup` puts it on a website, and `h5p-to-scorm` makes it a -SCORM zip for an LMS. +it, wrong answers included; its Download button saves a copy. Where the command does not run on +the user's computer, hand over the file and the command. If you already have a browser tool, +add `--no-open` and play the address it prints with that tool. Do not write a browser script to +do it: the person's own play is the check, and a script of your own costs more than the build. + +Deliver: + +- the `.h5p` and the source; +- `report.json`, `screenshot.png` and the report's full `revision`, from the run that passed; + where it could not run, no report and call the package **unverified**; where it ran but failed, + give its report and reasons and say the package **failed verification**; +- the preview command, and the build's notes; +- what a pass means: it starts and draws, not that it is accurate, accessible or right for + every LMS; +- that it carries the editor libraries an H5P site's upload check asks for, so a Moodle with no + library installed accepts it (the one site tried); +- that it carries H5P's libraries, each under its own licence, most MIT, listed in the pack's + [`libraries.txt`](https://github.com/missing-elements/h5p-offline-player/blob/main/packages/libraries/libraries.txt), + so the user checks those terms before they distribute it; +- where it goes next: the H5P Preview extension (`MissingElements.h5p-preview`) plays it in + VS Code, Cursor or VSCodium, `h5p-player-setup` puts it on a website, and `h5p-to-scorm` + makes it a SCORM zip for an LMS.