Thank you for contributing to h5p-toolkit.
This repository is a pnpm workspace containing the player, the H5P runtime, the library bundle, the normalizer, the verifier, the cmi5 package, the embed site writer, the demo application and a project that tests the agent skills' scripts. Read the development guide before making changes. It explains the workspace layout, generated assets, and the commands that apply to each package.
The player handles untrusted archives across a page, Service Worker, and dedicated worker. For architectural constraints and security boundaries, read AGENTS.md and the files in design/ it points to.
- Node.js 22 LTS or 24 LTS
- pnpm 10
- Chromium for browser tests
git clone https://github.com/missing-elements/h5p-toolkit.git
cd h5p-toolkit
pnpm install --frozen-lockfile
pnpm --filter @missing-elements/h5p-offline-player exec playwright install chromiumStart the demo development server:
pnpm devRun the checks that cover your change:
pnpm test:unit
pnpm test:browser
pnpm typecheck
pnpm buildpnpm test:browser exercises the player in Chromium, including its Service
Worker and Jobs worker. Run it for changes to playback, storage, worker,
network, or browser-facing behavior. A pull request's CI run tests, in Chromium,
only the packages it changes and those that depend on them; a change outside the
packages, such as the lockfile or a workflow, tests every package. Firefox,
WebKit and three slow browser files run only in CI's weekly run and when it is
run by hand. So for a change to the Service Worker, the Jobs worker, storage or
the demo's pages, run them in Firefox and WebKit yourself, one engine at a time,
after installing them with
pnpm --filter @missing-elements/h5p-offline-player exec playwright install firefox webkit:
H5P_TEST_BROWSER=firefox pnpm test:engine
H5P_TEST_BROWSER=webkit pnpm test:engineRun the smallest relevant check first, then expand coverage when the change affects more than one package.
Do not commit generated dist, public/frame-assets, the runtime's index.js,
or fixture output unless the repository's existing release or asset-generation
workflow explicitly requires it.
Before opening a pull request:
- Keep the change focused and add or update tests for behavior changes.
- Run the relevant checks and state the commands and results in the pull request.
- Update documentation when a public API, deployment requirement, security boundary, or user-visible behavior changes. A change to anything docs/compatibility.md covers is a version decision: say so in the pull request.
- Preserve streaming behavior: do not introduce whole-archive or whole-media buffering.
- Preserve archive-name validation, origin checks, Service Worker boundaries, and the frame Content Security Policy.
- Preserve keyboard accessibility and visible focus behavior when changing the player, frame, demo, or installable app.
- Do not disclose security vulnerabilities in public issues or pull requests; follow SECURITY.md instead.
Describe the problem, the solution, and how you verified the change. Include a screenshot, recording, or minimal reproduction when it helps reviewers assess a user-visible change.