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
9 changes: 6 additions & 3 deletions design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
11 changes: 7 additions & 4 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,9 @@ An unknown name lists the pack's content types.

## Options

- `--libraries <folder>`: another copy of the pack's `parts/` folder, in place of the pinned one.
- `--libraries <folder>` or `--libraries=<folder>`: 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

Expand Down Expand Up @@ -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`.

Expand Down
35 changes: 22 additions & 13 deletions packages/author/bin/h5p-author.mjs
Original file line number Diff line number Diff line change
@@ -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'

Expand All @@ -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<string, string | true>} */
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 {
Expand Down
20 changes: 12 additions & 8 deletions packages/author/lib/browser.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
*/
Expand All @@ -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<string, unknown>, content: Record<string, unknown>, libraries: string[],
* 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[]
* }} 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<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 @@ -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)
Expand Down
19 changes: 13 additions & 6 deletions packages/author/lib/build.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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"')
Expand Down Expand Up @@ -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<unknown>} writer
* @param {{ manifest: Record<string, unknown>, content: Record<string, unknown>, selected: Map<string, import('./pack.mjs').PartLibrary>, install: Map<string, import('./pack.mjs').PartLibrary> }} built
* @param {import('./pack.mjs').Pack} pack
* @param {() => Promise<void>} 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)
}

Expand Down
16 changes: 13 additions & 3 deletions packages/author/lib/generator.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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
Expand All @@ -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
}

Expand Down
26 changes: 20 additions & 6 deletions packages/author/lib/media.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -176,7 +189,7 @@ export class MediaStore {
this.idle = idle
/** @type {StagedFile<F>[]} */
this.files = []
/** @type {Map<string, { name: string, mime: string, width?: number, height?: number }>} by source, so one file named twice is copied once */
/** @type {Map<string, { name: string, mime: string, width?: number, height?: number }>} by kind and source, so one file named twice for one kind is copied once */
this.known = new Map()
/** @type {Set<string>} */
this.names = new Set()
Expand Down Expand Up @@ -213,7 +226,8 @@ export class MediaStore {
return { path: source, copyright }
}
const types = /** @type {Record<string, string>} */ (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 }
Expand All @@ -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
Expand Down Expand Up @@ -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
}
Expand Down Expand Up @@ -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(', ')}`)
Expand All @@ -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 {
Expand Down
15 changes: 8 additions & 7 deletions packages/author/lib/node.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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<Uint8Array>} */ (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<Uint8Array>} */ (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()] })
}
Expand Down
Loading
Loading