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
57 changes: 46 additions & 11 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@ player's unless a section says otherwise.
packages/player/ @missing-elements/h5p-offline-player — the published package
src/
h5p-offline-player.ts the <h5p-player> custom element — the only public entry point
plan.ts `./plan` -> dist/h5p-plan.js: the player's library rules (`planPack`, `librariesNamedIn`,
`addonPatterns`, `textMatches`, `dependenciesIn`) for the packages that write what it
plays; not covered by docs/compatibility.md, so they pin the player exactly (#106)
jobs-worker-handle.ts starts the Jobs worker from the first script the page's CSP allows, holding jobs until it runs
user-data-store.ts the learner's saved state for `resume`, in a database of the page's own
shadow.css the element's own box, imported `?inline` so Vite minifies it into the bundle
Expand All @@ -57,6 +60,9 @@ packages/player/ @missing-elements/h5p-offline-player — the published
revision.ts `withProvenance` and `indexFingerprint`: the build every statement names;
`librariesFingerprint`, one for the parts of the pack a package used
pack.ts `packLibrariesIn`: a pack index held to its shape; imports nothing, the element carries it
content-libraries.ts which libraries `h5p.json`, a `library.json` and content's parameters name, and an
addon's patterns: out of package-reader.ts on 2026-11-02, so that the plan and
`./plan` carry no zip.js (#106)
pack-index.ts generated by sync-h5p-assets from packages/libraries/parts/index.json: the pinned
pack's index, which the worker plans from and checks each part against
metadata.ts `h5p.json`'s metadata in the shape the runtime reads, held to the core's licence table
Expand All @@ -83,7 +89,8 @@ packages/player/ @missing-elements/h5p-offline-player — the published
warm.ts walks the library spans off one ranged request each and caches their entries
scripts/ sync-h5p-assets (builds the runtime package and copies its dist/ to public/frame-assets/,
writes frame-fonts.ts and pack-index.ts, stamps the versions), build-workers,
build-fixtures, prepack;
build-plan (dist/h5p-plan.js alone, which `prepare:dev` and h5p-author's tests
run, since h5p-author imports it), build-fixtures, prepack;
scripts/lib/worker-bundle.mjs builds both workers, and a host's own worker with the
handlers mounted (the demo uses it for h5p-sw.js and the app's sw.js)
vite.config.ts the library build and the test runner
Expand Down Expand Up @@ -170,8 +177,12 @@ packages/verify/ @missing-elements/h5p-verify — plays a package headl
packages/author/ @missing-elements/h5p-author — a playable .h5p of any content type in the pack from a short
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 and localized, the
content generated, media copied, layouts run, the archive written
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
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
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)
Expand All @@ -184,10 +195,10 @@ packages/author/ @missing-elements/h5p-author — a playable .h5p of an
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
tests/ node tests: the generator, text and translations, layouts and schema,
builds with media from disk and a local server, the command, the quiz
format; fixtures/ the quiz format's two examples, which apps/skills
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
types/ generated, not in git: the declarations

Expand Down Expand Up @@ -390,7 +401,8 @@ pnpm typecheck # every package
pnpm build # the player: types, element, both workers; builds the runtime package on the way
pnpm normalize course.h5p # rewrite a package so it streams: media stored, mp4 index first
pnpm verify course.h5p # play a package in a headless browser and report whether it works
pnpm author build source.json course.h5p # a package of any content type in the pack from a short source
pnpm author build source.json course.h5p # a package of any content type in the pack from a short source;
# after pnpm build, or the player's build:plan, whose dist/h5p-plan.js it imports
pnpm --filter @missing-elements/h5p-author sync:skill # the h5p-author skill's type files' fields, from the pack
pnpm --filter h5p-preview package # the VS Code extension's .vsix, from the player as pnpm build left it
pnpm --filter h5p-preview test:vscode # its suite in a VS Code it downloads; under xvfb-run on Linux
Expand Down Expand Up @@ -1969,7 +1981,7 @@ 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. Seven things the code does not say by itself:
to 3,000. Eight things the code does not say by itself:

- **One generator, two ways to run it.** `ContentGenerator` was the sweep's
(`apps/demo/scripts/lib/sweep-content.mjs`), and moved here so there is one copy; the sweep runs
Expand Down Expand Up @@ -2035,7 +2047,28 @@ to 3,000. Seven things the code does not say by itself:
packages/libraries has, so a release builds with the libraries it was tested with and one command
needs no project set up; `--libraries` names another `parts/` folder. Each part is checked
against the index's SHA-256 before it is read. `prepublishOnly` refuses while that version is not
on npm with this checkout's index (`scripts/check-pack-published.mjs`), as the player's does.
on npm with this checkout's index (`scripts/check-pack-published.mjs`, which checks the player it
pins too, next bullet), as the player's does.
- **The player's library rules, not copies of them** (2026-11-02, #106, the owner's rule: reuse what
another package has, and extend it where needed). Which libraries content names, an addon's
patterns and what they match, and which parts of the pack a package needs are the player's: the
build plans what a package carries with `planPack` from the player's `./plan`, for a package that
carries nothing yet, so a package carries the parts the player would take from the pack for it.
Two things stay here. A check that every library the content and the parts name was planned,
since the plan leaves a gap without a word. And the order: depth first from the content type, as
the closure the plan replaced listed them, which `h5p.json` and the zip's folders follow, because
the runtime keeps that order between libraries that do not depend on each other and so decides
whose stylesheet comes later; `build.test.ts` holds a build's `h5p.json` to it, derived from the
parts' own `library.json` files. All 32 type files' examples came out with the libraries, order,
folders and notes of the build before. The old closure also followed `dynamicDependencies`, which
no library in the pack has (checked the same day). `./plan` is not covered by
docs/compatibility.md, so the dependency is `workspace:*`, the player's exact version, published
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.
- **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 @@ -2256,7 +2289,8 @@ one row each; an LMS added here gets a row there.
(the owner's call, the same day: those exports are what many teachers have). The writer runs the
player's planner as the launch page has the element run it, filling gaps only: `planParts` is
`planPack` with `refresh` off and nothing attached before, and `librariesNamedIn`,
`addonPatterns`, `textMatches` and `ownLibraries` are copies of the player's. Keep them in step.
`addonPatterns`, `textMatches` and `ownLibraries` are copies of the player's. Keep them in step
until #109 has the writer import them from the player's `./plan`, as h5p-author does.
It writes those parts into `libraries/`, with an `index.json` that lists only them, and the page
names the folder with `libraries="pack"`, `pack-base` and `refresh-libraries="off"`. The element
then plans the same parts and finds each in the zip, and plays a package's own libraries as
Expand Down Expand Up @@ -2605,6 +2639,7 @@ Three artefacts, built three different ways, because they are consumed three dif
| `dist/h5p-sw.js` | esbuild, IIFE | Registered by URL; has to run on a site with no build step |
| `dist/h5p-sw-mount.js` | esbuild, ESM | For hosts that enforce one worker per origin |
| `dist/h5p-jobs.js` | esbuild, IIFE | The Jobs worker as a file, for a page whose CSP refuses a `blob:` worker |
| `dist/h5p-plan.js` | esbuild, ESM, not minified | The player's library rules, `./plan`, for the packages that write what it plays; the build fails if zip.js gets in |
| `packages/runtime/dist/` | `packages/runtime/scripts/build.mjs` | The H5P core from `vendor/h5p-core/`, its scripts joined and minified under a licence header, its stylesheets rebuilt to stand alone, and the boot script; a package of its own, GPL |
| `apps/demo/dist-demo/` | `apps/demo/scripts/build-demo.mjs` | The hosted demo: the pages, and `dist/`'s layout at the site root |

Expand Down
4 changes: 3 additions & 1 deletion docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,9 @@ warning can come in any release.
with the pack.
- Exports and files this page does not name: a package's other exports, the rest of the
player's `dist/`, the files inside the runtime's. Nor anything reached by a path a package does
not export.
not export. Among them the player's `./plan`, its library rules for the packages of this
repository that write what it plays, which depend on an exact version of the player for that
reason.
- The demo site, including `/app/` and `/embed` there, and this repository's scripts and
workflows.

Expand Down
25 changes: 25 additions & 0 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,31 @@ const { output, manifest, content, libraries, translations, notes, media } =
libraries })` returns the field list. `ContentGenerator` is the engine underneath, also run by the
repository's sweep of every content type.

A tool beside the build takes the libraries as the build loads them, the generator, and the
build's rules for text:

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

const params = { questions: ['Die *Donau* mündet ins Schwarze Meer.'] }
const pack = await openPack()
try {
const { entries, main, translations } = await loadLibraries(pack, { type: 'H5P.Blanks', language: 'de', params })
const content = new ContentGenerator(entries).generate(main, params)
} finally {
await pack.close()
}
```

`openPack(libraries)` opens the pinned pack, or another copy's `parts/` folder. `loadLibraries`
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.

## What it does not do

It checks structure, not pedagogy: whether the answers are right, the questions fair, or the
Expand Down
14 changes: 13 additions & 1 deletion packages/author/lib/author.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@
* @missing-elements/h5p-author: a playable .h5p of any content type in the H5P hub's library pack,
* from a short JSON source. The source writes only what the defaults cannot know; everything else
* comes from the libraries' own semantics and translations, and the libraries from the pack this
* package pins, checked against its index.
* package pins, checked against its index. A tool beside the build takes the libraries as the build
* loads them (`openPack`, `loadLibraries`) and its rules for text (`markupText`, `plainText`,
* `allowedTags`).
*/

import { openPack } from './pack.mjs'
Expand All @@ -11,13 +13,23 @@ import { LAYOUTS } from './types.mjs'

export { buildPackage, SourceError } from './build.mjs'
export { ContentGenerator, librariesIn, libraryString } from './generator.mjs'
export { loadLibraries } from './libraries.mjs'
export { openPack } from './pack.mjs'
export { GENERATED_END, GENERATED_START } from './schema.mjs'
export { allowedTags, markupText, plainText } from './text.mjs'

/**
* @typedef {import('./build.mjs').Source} Source
* @typedef {import('./build.mjs').BuildResult} BuildResult
* @typedef {import('./build.mjs').BuildOptions} BuildOptions
* @typedef {import('./generator.mjs').GeneratorOptions} GeneratorOptions
* @typedef {import('./generator.mjs').PackEntry} PackEntry
* @typedef {import('./libraries.mjs').LibraryRecord} LibraryRecord
* @typedef {import('./libraries.mjs').LibrarySource} LibrarySource
* @typedef {import('./libraries.mjs').LoadedLibraries} LoadedLibraries
* @typedef {import('./translate.mjs').TranslationReport} TranslationReport
* @typedef {import('./pack.mjs').IndexEntry} IndexEntry
* @typedef {import('./pack.mjs').PartLibrary} PartLibrary
*/

/**
Expand Down
Loading
Loading