From dd045c654906194558f15f14a76f0e88a83f9666 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Wed, 18 Nov 2026 14:31:15 +0200 Subject: [PATCH 1/4] chore(player): the README's npm copy keeps the package's name as its title (#234) --- design/build.md | 5 +++-- design/licensing.md | 5 +++-- packages/player/scripts/prepack.mjs | 18 ++++++++++++------ 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/design/build.md b/design/build.md index 869ac294..b9b39f47 100644 --- a/design/build.md +++ b/design/build.md @@ -142,8 +142,9 @@ went; `typecheck` and `prepack` both run it. Three rules, with TypeScript 7: build) so a broken tree cannot ship; the browser suite is left out because it needs an installed Chromium. Firefox, WebKit and the slow browser files run only in CI's weekly run and a run by hand, so before publishing the player, run CI by hand on main (`gh workflow run ci.yml`) and wait for -green. Then `prepack` copies the root README and LICENSE into the package, which is where npm -takes them from. The repository sets no `ignore-scripts`, so `prepublishOnly` runs; pnpm 10 blocks +green. Then `prepack` copies the root LICENSE into the package, which is where npm takes it +from, and the root README with the package's name for its title: the root one is titled for the +toolkit, the repository. The repository sets no `ignore-scripts`, so `prepublishOnly` runs; pnpm 10 blocks dependency scripts by itself. The build deletes `types/` and the TypeScript build info first: `tsc -b` never removes a declaration whose source was deleted. diff --git a/design/licensing.md b/design/licensing.md index fa94236e..1d045525 100644 --- a/design/licensing.md +++ b/design/licensing.md @@ -90,8 +90,9 @@ library pack", which nobody sees. Changing that one changes every part's bytes, so every package's `libraries` revision, and every learner's saved state starts over once; it goes with the next pack release that rewrites every part anyway. The VS Code extension and the MCP server, "H5P Author MCP by Missing Elements", were named to the rule from -the start, and so is the README's title, "H5P Toolkit by Missing Elements", which is also the -player's on npm, since `prepack` copies the README. Not decided: the site's address, +the start, and so is the README's title, "H5P Toolkit by Missing Elements". The player's copy of +the README on npm is titled with the package's name instead, whose scope names the author. +Not decided: the site's address, `h5p-offline-player.vercel.app`, which names no owner (the policy approves "h5p.terrisblog.com" and refuses "h5pbootcamp.com"), and the tab title "H5P player" of `/embed` and the embed package's page, a generic use. Two limits outweigh any name: the automatic licence covers free, diff --git a/packages/player/scripts/prepack.mjs b/packages/player/scripts/prepack.mjs index 7421250b..99022bd9 100644 --- a/packages/player/scripts/prepack.mjs +++ b/packages/player/scripts/prepack.mjs @@ -1,18 +1,24 @@ -import { copyFile } from 'node:fs/promises' +import { copyFile, readFile, writeFile } from 'node:fs/promises' import { resolve } from 'node:path' /** * Puts the repository's README and LICENSE into the package just before it is packed. npm takes * both from the package's own folder, and the README is the repository's landing page as well, * so it lives at the root and is copied here rather than kept twice. The copies are ignored by - * git. The README's one relative link, `LICENSE`, resolves in both places. + * git. The README's one relative link, `LICENSE`, resolves in both places. The root README is + * titled for the repository, the toolkit; on npm the page is this package's, so the copy takes + * the package's name as its title instead. */ const packageDir = resolve(import.meta.dirname, '..') const repositoryRoot = resolve(packageDir, '..', '..') -for (const name of ['README.md', 'LICENSE']) { - await copyFile(resolve(repositoryRoot, name), resolve(packageDir, name)) -} +await copyFile(resolve(repositoryRoot, 'LICENSE'), resolve(packageDir, 'LICENSE')) -console.log('[prepack] README.md and LICENSE copied from the repository root') +const { name } = /** @type {{ name: string }} */ (JSON.parse(await readFile(resolve(packageDir, 'package.json'), 'utf8'))) +const readme = await readFile(resolve(repositoryRoot, 'README.md'), 'utf8') +const title = /^# [^\n]*\n/ +if (!title.test(readme)) throw new Error('README.md does not start with a "# " title') +await writeFile(resolve(packageDir, 'README.md'), readme.replace(title, `# ${name}\n`)) + +console.log(`[prepack] LICENSE copied, and README.md titled ${name}`) From 4e93d1357ebfe91a6b6b4347bbc3a0b5b43107e3 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Wed, 18 Nov 2026 14:34:48 +0200 Subject: [PATCH 2/4] chore(player): a README that is only its title is copied too (#234) --- packages/player/scripts/prepack.mjs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/player/scripts/prepack.mjs b/packages/player/scripts/prepack.mjs index 99022bd9..86420afc 100644 --- a/packages/player/scripts/prepack.mjs +++ b/packages/player/scripts/prepack.mjs @@ -17,8 +17,9 @@ await copyFile(resolve(repositoryRoot, 'LICENSE'), resolve(packageDir, 'LICENSE' const { name } = /** @type {{ name: string }} */ (JSON.parse(await readFile(resolve(packageDir, 'package.json'), 'utf8'))) const readme = await readFile(resolve(repositoryRoot, 'README.md'), 'utf8') -const title = /^# [^\n]*\n/ +// The title line up to its end, newline or not, so what follows it is copied as it is. +const title = /^# [^\n]*/ if (!title.test(readme)) throw new Error('README.md does not start with a "# " title') -await writeFile(resolve(packageDir, 'README.md'), readme.replace(title, `# ${name}\n`)) +await writeFile(resolve(packageDir, 'README.md'), readme.replace(title, `# ${name}`)) console.log(`[prepack] LICENSE copied, and README.md titled ${name}`) From 3ed6d9b9c110b0a377cf5ffa01ff91de59ab4286 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Wed, 18 Nov 2026 14:43:58 +0200 Subject: [PATCH 3/4] docs: the README presents the whole toolkit, and the player keeps a README of its own for npm (#234) --- .gitignore | 3 +- README.md | 180 +++++++++++++++------------- design/build.md | 4 +- design/licensing.md | 4 +- packages/player/README.md | 115 ++++++++++++++++++ packages/player/scripts/prepack.mjs | 21 +--- 6 files changed, 221 insertions(+), 106 deletions(-) create mode 100644 packages/player/README.md diff --git a/.gitignore b/.gitignore index ce53c7d9..7bc22c40 100644 --- a/.gitignore +++ b/.gitignore @@ -11,8 +11,7 @@ types # reproducible from source. public -# Copied from the repository root by the player's `prepack`, so npm finds them in the package. -packages/player/README.md +# Copied from the repository root by the player's `prepack`, so npm finds it in the package. packages/player/LICENSE # The same for the normalizer, the verifier, the author, the cmi5 wiring and the embed site writer, whose `prepack` copies the LICENSE. packages/normalize/LICENSE diff --git a/README.md b/README.md index 7366caa1..cca09c4a 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,56 @@ # H5P Toolkit by Missing Elements -[![npm](https://img.shields.io/npm/v/%40missing-elements%2Fh5p-offline-player)](https://www.npmjs.com/package/@missing-elements/h5p-offline-player) -[![licence](https://img.shields.io/npm/l/%40missing-elements%2Fh5p-offline-player)](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE) - -Self-hosted [H5P](https://h5p.org) without an H5P server. One web component plays `.h5p` files -from your own URLs or from disk, on static hosting you control: no Moodle, WordPress or Lumi, no -backend, and no service of ours or H5P Group's between your learners and your content. +Everything you needed an [H5P](https://h5p.org) server for (playing, building, checking, +packaging for an LMS) as static files, command-line tools and agent skills. **[Live player demo](https://h5p-offline-player.vercel.app/)** · +[Build with AI](https://missing-elements.github.io/h5p/build/) · [Offline app](https://h5p-offline-player.vercel.app/app/) · [H5P to SCORM](https://h5p-offline-player.vercel.app/demo/scorm.html) · -[Lovable example](https://embed-h5p-file.lovable.app/) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=MissingElements.h5p-preview) -Version 1 since October 2026; [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) -says what a version number promises. **Every week** a job rebuilds the library pack from the H5P -hub and the interface strings from Moodle's translations, opens a pull request when either -changed, and plays every content type in the pack, trusted and untrusted. - -## Features - -- **Plays the packages people have.** Large ones stream, and exports without their libraries, as - h5p.com and h5p.org make them, play against a [library pack](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) - of the 53 content types the H5P hub serves. -- **Plays packages you did not make** with [`untrusted`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md): none of their - code runs, and their content is checked by a port of H5P's own validator. -- **Reports results you can audit:** xAPI statements that name the - [build of the package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) they came from, [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md), [resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md), and a - [SCORM zip](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms): SCORM 1.2, checked in - Moodle, ILIAS, OpenOLAT, Chamilo, SCORM Cloud and Frappe LMS, or 2004, checked in Moodle and - SCORM Cloud. -- **No tracking:** no account, cookies or telemetry, and nothing it stores leaves the learner's - browser. The library pack comes from jsDelivr unless you serve a copy +The player and the packages around it are at version 1 since October 2026, and +[Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) +says what a version number promises; the author package, the MCP server and the VS Code +extension are 0.x. **Every week** a job rebuilds the library pack from the H5P hub and the +interface strings from Moodle's translations, opens a pull request when either changed, and plays +every content type in the pack, trusted and untrusted. + +## What it does + +| To | Use | +|---|---| +| Play `.h5p` files on your site, from your own URLs or from disk | [``](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/player#readme), a web component | +| Play them from a domain of your own, or hand an LMS a SCORM zip or a cmi5 unit | [`h5p-embed`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#readme), [`h5p-cmi5`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/cmi5#readme) | +| Build an activity of any content type from a prompt or a short JSON source | the [`h5p-author` skill](https://github.com/missing-elements/h5p-toolkit/tree/main/skills/h5p-author), [the build page](https://missing-elements.github.io/h5p/build/), or [`h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) in Claude Desktop | +| Check that a package plays before you hand it over | [`h5p-verify`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/verify#readme) | +| Make a package's video start at once | [`h5p-normalize`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/normalize#readme) | +| Play `.h5p` files with no network, or in your editor | [the offline app](https://h5p-offline-player.vercel.app/app/), [H5P Preview](https://marketplace.visualstudio.com/items?itemName=MissingElements.h5p-preview) for VS Code | + +## Why this one + +- **No H5P server anywhere.** H5P usually runs in Moodle, WordPress or Drupal with its plugin, on + an h5p.com account, or in Lumi on a desktop. Here a `.h5p` plays from a URL on static hosting, + with nothing unzipped, and the tools run on your computer or in your agent. + [The comparison](https://h5p-offline-player.vercel.app/demo/compare.html) goes through + h5p-standalone, Lumi, h5p.com and the plugins. +- **The packages people have.** Exports without their libraries, as h5p.com and h5p.org make + them, play against a library pack of every content type the H5P hub serves, and packages you + did not make play [`untrusted`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md), + with none of their code run. +- **What a model builds is checked.** `h5p-author` writes a package that carries its libraries, + which Moodle accepts as an upload, and `h5p-verify` plays it in the real H5P runtime in a + headless browser before anyone hands it over. +- **Nothing passes through a server of ours:** no account, cookies or telemetry, and the library + pack comes from jsDelivr unless you serve a copy ([privacy](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md)). -- **Works offline, in the content's language:** an installable app, and H5P's own buttons in - English and 56 other languages. -- **Tested in Chromium, Firefox and WebKit** on every change, and in Safari on macOS and iOS by - hand ([browsers](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md#browsers)). -- **Comes with tools:** [`h5p-verify`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/verify.md) checks that a package plays, - [`h5p-normalize`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/streaming-video.md) makes its video stream, and - [`h5p-author`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/author#readme) builds one from a short JSON source, which a - Moodle site accepts as an upload too. [`h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) - brings the build and the check to an app with no shell, such as Claude Desktop. - -It is a player, not an editor, and it stores no results: its events go wherever your page sends -them. Coming from [h5p-standalone](https://github.com/tunapanda/h5p-standalone)? This player -reads the `.h5p` itself, with nothing to unzip, and -[takes its options by the same names](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md). + +It is not an editor: H5P's own editor is not here, so content comes from the tools above or from +an H5P site. Nothing here stores results either: xAPI events go wherever your page sends them. ## Quick start -With Vite or webpack 5; both packages ship TypeScript declarations: +**Play** a package on your site, with Vite or webpack 5: ```bash npm install @missing-elements/h5p-offline-player @missing-elements/h5p-runtime @@ -64,50 +64,37 @@ npm install @missing-elements/h5p-offline-player @missing-elements/h5p-runtime import '@missing-elements/h5p-offline-player' import { runtime } from '@missing-elements/h5p-runtime' -const player = document.querySelector('h5p-player') -player.runtime = runtime -player.addEventListener('xapi', (e) => console.log(e.detail.statement)) +document.querySelector('h5p-player').runtime = runtime ``` -The bundler emits the Service Worker and the runtime (the H5P core, a package of its own because -it is GPL-3.0) as files, so there is nothing to copy. The page must be on `https://` or -`localhost`, and a package from another origin needs CORS headers on its host. A package that -carries its libraries plays as it is; one exported without them, as h5p.com exports, needs -`libraries="pack"`. +[Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) +covers pages without a bundler, other bundlers, CORS, and which setup suits packages you did not +make. -Packages you did not make, or a site with signed-in users: play every package `untrusted`, or -embed the player from a domain of its own, as -[Which setup](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md#which-setup) explains. -[Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) also covers a page without a bundler, Rollup and -esbuild, and the one-prompt install on Lovable; -[the element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) lists every attribute, property and event. +**Build** with AI, in Claude Code or another agent that runs commands: -## Documentation +```bash +npx skills add missing-elements/h5p-toolkit --skill h5p-author +``` -- **Set up:** [Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) · - [The element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) · - [Troubleshooting](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/troubleshooting.md) · - [Single-worker hosts and upgrades](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/single-worker.md) · - [Coming from h5p-standalone](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md) -- **Packages:** [Libraries](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) · - [Packages you did not make](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md) · - [Video that cannot stream](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/streaming-video.md) · - [Verifying a package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/verify.md) · - [The frame's CSP](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/frame-csp.md) -- **Results:** [Resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md) · - [Which build a learner completed](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) · - [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md) · - [A SCORM package](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms) -- **Policies:** [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) · - [Privacy and data protection](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md) · - [Accessibility](https://github.com/missing-elements/h5p-toolkit/blob/main/ACCESSIBILITY.md) · - [Security](https://github.com/missing-elements/h5p-toolkit/blob/main/SECURITY.md) +Then ask it for an activity, such as "a five-question quiz on the water cycle, as H5P": it asks +which content type, builds the `.h5p`, checks it and opens it for you to play. In a chat app, +[the build page](https://missing-elements.github.io/h5p/build/) turns what the chat wrote into the +file, in your browser; in Claude Desktop, +[`h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) builds +it onto your disk. + +**Check** a package, with Node 22 or later: + +```bash +npx @missing-elements/h5p-verify@latest course.h5p +``` ## Packages | Package | What it is | |---|---| -| [`@missing-elements/h5p-offline-player`](https://www.npmjs.com/package/@missing-elements/h5p-offline-player) | The `` element and its workers | +| [`@missing-elements/h5p-offline-player`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/player#readme) | The `` element and its workers | | [`@missing-elements/h5p-runtime`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/runtime#readme) | The H5P core the player loads in its frame, GPL-3.0 | | [`@missing-elements/h5p-libraries`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/libraries#readme) | The library pack: the runtime libraries of every content type the H5P hub serves | | [`@missing-elements/h5p-embed`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#readme) | The player page as a static site, and a package as a SCORM zip | @@ -141,8 +128,28 @@ npx skills add missing-elements/h5p-toolkit A chat app takes `h5p-author` as a zip that you upload or attach. Download it from [missing-elements.github.io/h5p/create-with-ai/#install](https://missing-elements.github.io/h5p/create-with-ai/#install), which says where it goes in each app. The zip holds the same h5p-author release as the site's -build page runs. In Claude Desktop, [`h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) -builds onto your disk instead. +build page runs. + +## Documentation + +- **Set up:** [Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) · + [The element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) · + [Troubleshooting](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/troubleshooting.md) · + [Single-worker hosts and upgrades](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/single-worker.md) · + [Coming from h5p-standalone](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md) +- **Packages:** [Libraries](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) · + [Packages you did not make](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md) · + [Video that cannot stream](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/streaming-video.md) · + [Verifying a package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/verify.md) · + [The frame's CSP](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/frame-csp.md) +- **Results:** [Resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md) · + [Which build a learner completed](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) · + [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md) · + [A SCORM package](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms) +- **Policies:** [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) · + [Privacy and data protection](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md) · + [Accessibility](https://github.com/missing-elements/h5p-toolkit/blob/main/ACCESSIBILITY.md) · + [Security](https://github.com/missing-elements/h5p-toolkit/blob/main/SECURITY.md) ## Contributing @@ -154,13 +161,16 @@ the design and the reasons behind it. Report vulnerabilities privately, as ## Licence -The player is MIT ([LICENSE](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE)); -its Service Worker bundles [zip.js](https://github.com/gildas-lormeau/zip.js), BSD-3-Clause -([NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/player/NOTICE.md)). -The H5P runtime the frame loads, the H5P core from [h5p-php-library](https://github.com/h5p/h5p-php-library) -and the script that boots it, is GPL-3.0 and published separately as -[`@missing-elements/h5p-runtime`](https://www.npmjs.com/package/@missing-elements/h5p-runtime); +Every package is MIT ([LICENSE](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE)) +but two. The H5P runtime the player's frame loads, the H5P core from +[h5p-php-library](https://github.com/h5p/h5p-php-library) and the script that boots it, is GPL-3.0 +and published apart as [`@missing-elements/h5p-runtime`](https://www.npmjs.com/package/@missing-elements/h5p-runtime); the player talks to it only over HTTP and `postMessage`, and its [NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/runtime/NOTICE.md) -says what serving it entails. Whether the copyleft reaches the page around the player is a legal -question this README does not answer. +says what serving it entails. The library pack holds H5P's libraries, each under its own licence, +most MIT, as [its list](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/libraries/libraries.txt) +says. What a package bundles keeps its licence too: the player's Service Worker carries +[zip.js](https://github.com/gildas-lormeau/zip.js), BSD-3-Clause +([NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/player/NOTICE.md)). +Whether the copyleft reaches the page around the player is a legal question this README does not +answer. diff --git a/design/build.md b/design/build.md index b9b39f47..f52d0ec5 100644 --- a/design/build.md +++ b/design/build.md @@ -143,8 +143,8 @@ build) so a broken tree cannot ship; the browser suite is left out because it ne Chromium. Firefox, WebKit and the slow browser files run only in CI's weekly run and a run by hand, so before publishing the player, run CI by hand on main (`gh workflow run ci.yml`) and wait for green. Then `prepack` copies the root LICENSE into the package, which is where npm takes it -from, and the root README with the package's name for its title: the root one is titled for the -toolkit, the repository. The repository sets no `ignore-scripts`, so `prepublishOnly` runs; pnpm 10 blocks +from. The player's README is its own, `packages/player/README.md`, since the root one is the +toolkit's front page. The repository sets no `ignore-scripts`, so `prepublishOnly` runs; pnpm 10 blocks dependency scripts by itself. The build deletes `types/` and the TypeScript build info first: `tsc -b` never removes a declaration whose source was deleted. diff --git a/design/licensing.md b/design/licensing.md index 1d045525..64bad643 100644 --- a/design/licensing.md +++ b/design/licensing.md @@ -90,8 +90,8 @@ library pack", which nobody sees. Changing that one changes every part's bytes, so every package's `libraries` revision, and every learner's saved state starts over once; it goes with the next pack release that rewrites every part anyway. The VS Code extension and the MCP server, "H5P Author MCP by Missing Elements", were named to the rule from -the start, and so is the README's title, "H5P Toolkit by Missing Elements". The player's copy of -the README on npm is titled with the package's name instead, whose scope names the author. +the start, and so is the README's title, "H5P Toolkit by Missing Elements". The player's own +README, its page on npm, is titled with the package's name, whose scope names the author. Not decided: the site's address, `h5p-offline-player.vercel.app`, which names no owner (the policy approves "h5p.terrisblog.com" and refuses "h5pbootcamp.com"), and the tab title "H5P player" of `/embed` and the embed package's diff --git a/packages/player/README.md b/packages/player/README.md new file mode 100644 index 00000000..dc28ba7d --- /dev/null +++ b/packages/player/README.md @@ -0,0 +1,115 @@ +# @missing-elements/h5p-offline-player + +[![npm](https://img.shields.io/npm/v/%40missing-elements%2Fh5p-offline-player)](https://www.npmjs.com/package/@missing-elements/h5p-offline-player) +[![licence](https://img.shields.io/npm/l/%40missing-elements%2Fh5p-offline-player)](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE) + +Self-hosted [H5P](https://h5p.org) without an H5P server. One web component plays `.h5p` files +from your own URLs or from disk, on static hosting you control: no Moodle, WordPress or Lumi, no +backend, and no service of ours or H5P Group's between your learners and your content. + +**[Live player demo](https://h5p-offline-player.vercel.app/)** · +[Offline app](https://h5p-offline-player.vercel.app/app/) · +[H5P to SCORM](https://h5p-offline-player.vercel.app/demo/scorm.html) · +[Lovable example](https://embed-h5p-file.lovable.app/) · +[VS Code extension](https://marketplace.visualstudio.com/items?itemName=MissingElements.h5p-preview) + +Version 1 since October 2026; [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) +says what a version number promises. **Every week** a job rebuilds the library pack from the H5P +hub and the interface strings from Moodle's translations, opens a pull request when either +changed, and plays every content type in the pack, trusted and untrusted. + +## Features + +- **Plays the packages people have.** Large ones stream, and exports without their libraries, as + h5p.com and h5p.org make them, play against a [library pack](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) + of the 53 content types the H5P hub serves. +- **Plays packages you did not make** with [`untrusted`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md): none of their + code runs, and their content is checked by a port of H5P's own validator. +- **Reports results you can audit:** xAPI statements that name the + [build of the package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) they came from, [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md), [resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md), and a + [SCORM zip](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms): SCORM 1.2, checked in + Moodle, ILIAS, OpenOLAT, Chamilo, SCORM Cloud and Frappe LMS, or 2004, checked in Moodle and + SCORM Cloud. +- **No tracking:** no account, cookies or telemetry, and nothing it stores leaves the learner's + browser. The library pack comes from jsDelivr unless you serve a copy + ([privacy](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md)). +- **Works offline, in the content's language:** an installable app, and H5P's own buttons in + English and 56 other languages. +- **Tested in Chromium, Firefox and WebKit** on every change, and in Safari on macOS and iOS by + hand ([browsers](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md#browsers)). +- **Part of a toolkit:** [H5P Toolkit by Missing Elements](https://github.com/missing-elements/h5p-toolkit#readme) + also builds packages with AI, checks that they play, makes their video stream and turns them + into SCORM zips. + +It is a player, not an editor, and it stores no results: its events go wherever your page sends +them. Coming from [h5p-standalone](https://github.com/tunapanda/h5p-standalone)? This player +reads the `.h5p` itself, with nothing to unzip, and +[takes its options by the same names](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md). + +## Quick start + +With Vite or webpack 5; both packages ship TypeScript declarations: + +```bash +npm install @missing-elements/h5p-offline-player @missing-elements/h5p-runtime +``` + +```html + +``` + +```js +import '@missing-elements/h5p-offline-player' +import { runtime } from '@missing-elements/h5p-runtime' + +const player = document.querySelector('h5p-player') +player.runtime = runtime +player.addEventListener('xapi', (e) => console.log(e.detail.statement)) +``` + +The bundler emits the Service Worker and the runtime (the H5P core, a package of its own because +it is GPL-3.0) as files, so there is nothing to copy. The page must be on `https://` or +`localhost`, and a package from another origin needs CORS headers on its host. A package that +carries its libraries plays as it is; one exported without them, as h5p.com exports, needs +`libraries="pack"`. + +Packages you did not make, or a site with signed-in users: play every package `untrusted`, or +embed the player from a domain of its own, as +[Which setup](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md#which-setup) explains. +[Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) also covers a page without a bundler, Rollup and +esbuild, and the one-prompt install on Lovable; +[the element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) lists every attribute, property and event. + +## Documentation + +- **Set up:** [Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) · + [The element's API](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/api.md) · + [Troubleshooting](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/troubleshooting.md) · + [Single-worker hosts and upgrades](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/single-worker.md) · + [Coming from h5p-standalone](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/h5p-standalone.md) +- **Packages:** [Libraries](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/libraries.md) · + [Packages you did not make](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md) · + [Video that cannot stream](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/streaming-video.md) · + [Verifying a package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/verify.md) · + [The frame's CSP](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/frame-csp.md) +- **Results:** [Resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md) · + [Which build a learner completed](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) · + [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md) · + [A SCORM package](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms) +- **Policies:** [Compatibility](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md) · + [Privacy and data protection](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md) · + [Accessibility](https://github.com/missing-elements/h5p-toolkit/blob/main/ACCESSIBILITY.md) · + [Security](https://github.com/missing-elements/h5p-toolkit/blob/main/SECURITY.md) + +## Licence + +The player is MIT ([LICENSE](https://github.com/missing-elements/h5p-toolkit/blob/main/LICENSE)); +its Service Worker bundles [zip.js](https://github.com/gildas-lormeau/zip.js), BSD-3-Clause +([NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/player/NOTICE.md)). +The H5P runtime the frame loads, the H5P core from [h5p-php-library](https://github.com/h5p/h5p-php-library) +and the script that boots it, is GPL-3.0 and published separately as +[`@missing-elements/h5p-runtime`](https://www.npmjs.com/package/@missing-elements/h5p-runtime); +the player talks to it only over HTTP and `postMessage`, and its +[NOTICE.md](https://github.com/missing-elements/h5p-toolkit/blob/main/packages/runtime/NOTICE.md) +says what serving it entails. Whether the copyleft reaches the page around the player is a legal +question this README does not answer. diff --git a/packages/player/scripts/prepack.mjs b/packages/player/scripts/prepack.mjs index 86420afc..e82c917c 100644 --- a/packages/player/scripts/prepack.mjs +++ b/packages/player/scripts/prepack.mjs @@ -1,13 +1,11 @@ -import { copyFile, readFile, writeFile } from 'node:fs/promises' +import { copyFile } from 'node:fs/promises' import { resolve } from 'node:path' /** - * Puts the repository's README and LICENSE into the package just before it is packed. npm takes - * both from the package's own folder, and the README is the repository's landing page as well, - * so it lives at the root and is copied here rather than kept twice. The copies are ignored by - * git. The README's one relative link, `LICENSE`, resolves in both places. The root README is - * titled for the repository, the toolkit; on npm the page is this package's, so the copy takes - * the package's name as its title instead. + * Puts the repository's LICENSE into the package just before it is packed: npm takes it from the + * package's own folder, and it lives at the root, so it is copied here rather than kept twice. The + * copy is ignored by git. The README is the package's own, `README.md` beside this folder: the + * root one is the toolkit's front page, and npm shows this package's. */ const packageDir = resolve(import.meta.dirname, '..') @@ -15,11 +13,4 @@ const repositoryRoot = resolve(packageDir, '..', '..') await copyFile(resolve(repositoryRoot, 'LICENSE'), resolve(packageDir, 'LICENSE')) -const { name } = /** @type {{ name: string }} */ (JSON.parse(await readFile(resolve(packageDir, 'package.json'), 'utf8'))) -const readme = await readFile(resolve(repositoryRoot, 'README.md'), 'utf8') -// The title line up to its end, newline or not, so what follows it is copied as it is. -const title = /^# [^\n]*/ -if (!title.test(readme)) throw new Error('README.md does not start with a "# " title') -await writeFile(resolve(packageDir, 'README.md'), readme.replace(title, `# ${name}`)) - -console.log(`[prepack] LICENSE copied, and README.md titled ${name}`) +console.log('[prepack] LICENSE copied from the repository root') From 600fed7e427b59b4fce1ff8a7a82ffae787a9a0b Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Wed, 18 Nov 2026 14:48:02 +0200 Subject: [PATCH 4/4] docs: Firefox and WebKit run weekly and before releases; cmi5 and SCORM come from their packages; the quick start names libraries="pack" (#234) --- README.md | 2 ++ docs/compatibility.md | 7 ++++--- packages/player/README.md | 13 +++++++------ 3 files changed, 13 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index cca09c4a..3cc060da 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,8 @@ import { runtime } from '@missing-elements/h5p-runtime' document.querySelector('h5p-player').runtime = runtime ``` +A package that carries its libraries plays as it is; one exported without them, as h5p.com +exports, needs `libraries="pack"` on the element. [Setting up the player](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/setup.md) covers pages without a bundler, other bundlers, CORS, and which setup suits packages you did not make. diff --git a/docs/compatibility.md b/docs/compatibility.md index 01c6c378..5c56d738 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -160,9 +160,10 @@ in a major. None is in that state now. ## Browsers The player needs a secure context — https, or `localhost` — with Service Workers, the Cache API, -IndexedDB, Web Locks and `DecompressionStream` for `deflate-raw`. Its browser suite runs on every -change in Chromium, Firefox and WebKit, Playwright's builds of their current releases; Safari on -macOS and iOS is checked by hand. No version floor is published: a package that plays in a current +IndexedDB, Web Locks and `DecompressionStream` for `deflate-raw`. Its browser suite runs in +Chromium on every change, and in Firefox and WebKit every week and before each release of the +player, all three Playwright's builds of their current releases; Safari on macOS and iOS is +checked by hand. No version floor is published: a package that plays in a current browser and not in another that has those features is a bug, and worth reporting. Dropping an engine is a major change. diff --git a/packages/player/README.md b/packages/player/README.md index dc28ba7d..b8ea9fbf 100644 --- a/packages/player/README.md +++ b/packages/player/README.md @@ -26,17 +26,18 @@ changed, and plays every content type in the pack, trusted and untrusted. - **Plays packages you did not make** with [`untrusted`](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/untrusted.md): none of their code runs, and their content is checked by a port of H5P's own validator. - **Reports results you can audit:** xAPI statements that name the - [build of the package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) they came from, [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md), [resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md), and a - [SCORM zip](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms): SCORM 1.2, checked in - Moodle, ILIAS, OpenOLAT, Chamilo, SCORM Cloud and Frappe LMS, or 2004, checked in Moodle and - SCORM Cloud. + [build of the package](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/revision.md) they came from, and [resume](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/resume.md). + With [`h5p-cmi5`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/cmi5#readme), a page holding the player is a + [cmi5](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/cmi5.md) unit, and [`h5p-embed`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#a-scorm-package-for-an-lms) writes a package as a SCORM zip: + SCORM 1.2, checked in Moodle, ILIAS, OpenOLAT, Chamilo, SCORM Cloud and Frappe LMS, or 2004, + checked in Moodle and SCORM Cloud. - **No tracking:** no account, cookies or telemetry, and nothing it stores leaves the learner's browser. The library pack comes from jsDelivr unless you serve a copy ([privacy](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/privacy.md)). - **Works offline, in the content's language:** an installable app, and H5P's own buttons in English and 56 other languages. -- **Tested in Chromium, Firefox and WebKit** on every change, and in Safari on macOS and iOS by - hand ([browsers](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md#browsers)). +- **Tested in Chromium** on every change, in Firefox and WebKit every week and before each + release, and in Safari on macOS and iOS by hand ([browsers](https://github.com/missing-elements/h5p-toolkit/blob/main/docs/compatibility.md#browsers)). - **Part of a toolkit:** [H5P Toolkit by Missing Elements](https://github.com/missing-elements/h5p-toolkit#readme) also builds packages with AI, checks that they play, makes their video stream and turns them into SCORM zips.