@missing-elements/h5p-embed 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 missing-elements
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# @missing-elements/h5p-embed
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Self-hosted H5P embeds. One command writes the H5P embed page as a static site; you deploy it to
+a player domain of your own, and any site — a page builder, a hosted CMS, an LMS page, a portal
+with signed-in users — embeds a package with an iframe and one script line. No H5P server, no
+backend, and no third-party service between your learners and your content.
+
+```bash
+npx @missing-elements/h5p-embed h5p-player
+```
+
+```
+Wrote h5p-player/ (11.1 MB): the embed page, the player 0.5.1, the H5P runtime, the library pack.
+```
+
+Deploy the folder to any static host, then embed:
+
+```html
+<iframe src="https://h5p-player.example.net/?src=https://cdn.example.org/course.h5p"
+        allow="fullscreen" style="width: 100%; border: 0"></iframe>
+<script src="https://h5p-player.example.net/resizer.js"></script>
+```
+
+The script line sizes the iframe to the content. A page that already has h5p.org's
+`h5p-resizer.js` needs no second one; it speaks the same protocol.
+
+## Why a domain of its own
+
+An H5P package is JavaScript, and the player runs it on the origin that serves the page. On a
+domain that holds nothing else, a package cannot reach your site's page, cookies, storage or APIs.
+Use a separate registrable domain — `h5p-player.example.net`, not `h5p.example.com` — because a
+subdomain is the same site and receives cookies set for `.example.com`. Put no accounts, no
+cookies and nothing else on it.
+
+## Options
+
+| Option | Effect |
+|---|---|
+| `--packages <origins>` | Play packages, and fetch library bundles, only from these origins (this domain's own is always allowed). The page refuses anything else by name, and the policy's `connect-src` blocks it in the browser. Add `https://api.h5p.org` to allow `libraries=hub` |
+| `--ancestors <origins>` | Only these sites may frame the page: `frame-ancestors`, which only a header can carry |
+| `--no-libraries` | Leave out the 9.5 MB library pack; `libraries=pack` then means the hub, where allowed |
+| `--force` | Write into a folder that is not empty, replacing only this tool's files |
+
+Origins are written `https://host.example`, comma or space separated, with no path or trailing
+slash. `http://localhost` is accepted for trying it locally.
+
+List every host a package URL passes through. The page checks the address it is given, but the
+browser's policy also applies to each redirect, so a listed host that redirects to a CDN off the
+list fails as an ordinary network error, with nothing naming the list as the cause.
+
+A player domain for one organisation is best locked to its own hosts:
+
+```bash
+npx @missing-elements/h5p-embed h5p-player \
+  --packages https://cdn.example.org \
+  --ancestors "https://www.example.org https://lms.example.org"
+```
+
+## Hosting
+
+| Host | Policy and caching |
+|---|---|
+| Netlify, Cloudflare Pages | `_headers`, written beside the page |
+| Vercel | `vercel.json`, written beside the page; deploy the folder as a project |
+| GitHub Pages, S3, nginx, anything else | The page carries the policy in a `<meta>` tag. `--ancestors` needs a header: configure `Content-Security-Policy: frame-ancestors …` on the server, or leave it out |
+
+The site works at the domain's root or under a path (`https://example.github.io/player/`): every
+URL in it is relative, and the player's Service Worker takes the scope `<folder>/h5p/`. Serve it
+over https; a frame in a page on plain http has no Service Worker.
+
+`h5p-sw.js` should be served with `Cache-Control: no-cache`, as the header files say, so an update
+reaches learners on their next visit. To update, run the command again with `--force` and
+redeploy.
+
+## The address
+
+| Parameter | Effect |
+|---|---|
+| `src=<url>` | The package, required. Encode `&`, `#`, `+`, `%` and spaces in it |
+| `libraries=pack`, `hub` or `<url>` | Libraries for an export that has none (h5p.com and h5p.org exports usually do not). `pack` is the copy on this domain, with the hub behind it where allowed, or the hub alone on a site written with `--no-libraries`; several sources may be given, tried in order |
+| `frame`, `copyright`, `export`, `icon`, `reporting` | H5P's action bar under the content and its buttons |
+| `fullscreen=off` | No fullscreen button |
+| `preload=auto` | Start fetching media at once |
+| `activity-id=<IRI>` | The object id every xAPI statement names, instead of the package URL |
+| `custom-css=<url>` | A stylesheet of yours, loaded into the content |
+| `xapi=<origin>` | Relay statements to the embedding page, see below |
+
+Not available on the address: a custom script, and a learner's name. A script is a capability on
+the player's origin that a link should not hand out, and a name has no place in a URL.
+
+Opened on its own (not framed), the page asks before playing a package from another origin
+unless `--packages` names it: there, every package shares the domain's storage.
+
+## Results
+
+Add `&xapi=<the embedding page's origin>` and the frame posts every statement to that origin
+and no other:
+
+```js
+const frame = document.querySelector('iframe')
+addEventListener('message', ({ source, origin, data }) => {
+  if (source !== frame.contentWindow || origin !== 'https://h5p-player.example.net') return
+  if (data?.context !== 'h5p-offline-player') return
+  if (data.action === 'xapi') send(data.statement)      // every statement
+  if (data.action === 'finished') send(data.statement)  // the final one, with result.score
+})
+```
+
+The checks prove where a message came from, not what it says: a package can post any statement,
+so treat relayed results as the learner's report, not as proof for a grade. Each statement
+carries `context.revision`, a fingerprint of the package build.
+
+## As a library
+
+```js
+import { buildSite } from '@missing-elements/h5p-embed'
+
+await buildSite({ out: 'public/player', packages: ['https://cdn.example.org'] })
+```
+
+`@missing-elements/h5p-embed/embed.js` exports `startEmbed({ librariesPack, packages })`, the
+page's script, for a site that builds the page into its own pipeline.
+
+## Licences
+
+This package is MIT. The folder it writes also carries
+[`@missing-elements/h5p-runtime`](https://www.npmjs.com/package/@missing-elements/h5p-runtime), the
+H5P core runtime, under the GPL-3.0, as `frame-assets/` with its `LICENSE.txt` and `NOTICE.txt`;
+and, unless `--no-libraries`, the H5P hub's libraries under their own licences, listed in
+`libraries.txt`. `NOTICE.txt` in the folder says which file is what.

package/bin/h5p-embed.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import { relative } from 'node:path'
+import { parseArgs } from 'node:util'
+import { EmbedError, buildSite } from '../lib/build.mjs'
+
+const USAGE = `Usage: h5p-embed [folder] [options]
+
+Writes the H5P embed page as a static site, ready to deploy to a player domain of your own.
+The folder defaults to ./h5p-player.
+
+Options:
+  --packages <origins>   play packages, and fetch library bundles, only from these origins
+                         (comma or space separated; this site's own is always allowed). Add
+                         https://api.h5p.org to allow libraries=hub, and any host a package
+                         URL redirects to. Default: any https host.
+  --ancestors <origins>  only these sites may frame the page (frame-ancestors, sent as a header).
+                         Default: any site.
+  --no-libraries         leave out the 9.5 MB library pack that libraries=pack names
+  --force                write into a folder that is not empty, replacing only this tool's files
+  -h, --help             show this
+  -v, --version          print the version`
+
+let args
+try {
+  args = parseArgs({
+    allowPositionals: true,
+    options: {
+      packages: { type: 'string', multiple: true },
+      ancestors: { type: 'string', multiple: true },
+      'no-libraries': { type: 'boolean' },
+      force: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' }
+    }
+  })
+} catch (error) {
+  console.error(`h5p-embed: ${error instanceof Error ? error.message : error}\n\n${USAGE}`)
+  process.exit(2)
+}
+
+const { values, positionals } = args
+if (values.help) {
+  console.log(USAGE)
+  process.exit(0)
+}
+if (values.version) {
+  console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version)
+  process.exit(0)
+}
+if (positionals.length > 1) {
+  console.error(`h5p-embed: one folder at most, got ${positionals.length}\n\n${USAGE}`)
+  process.exit(2)
+}
+
+const megabytes = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`
+
+try {
+  const site = await buildSite({
+    out: positionals[0] ?? 'h5p-player',
+    libraries: !values['no-libraries'],
+    packages: values.packages ?? null,
+    ancestors: values.ancestors ?? null,
+    force: values.force ?? false
+  })
+  const below = relative(process.cwd(), site.out)
+  const folder = below === '' ? '.' : below.startsWith('..') ? site.out : below
+  const parts = [`the player ${site.version}`, 'the H5P runtime', site.libraries ? 'the library pack' : null].filter(Boolean)
+  console.log(`Wrote ${folder}/ (${megabytes(site.size)}): the embed page, ${parts.join(', ')}.`)
+  console.log(`Packages from: ${site.packages ? `this site, ${site.packages.join(', ')}` : 'any https host'}.`)
+  console.log(`Framed by: ${site.ancestors ? site.ancestors.join(', ') : 'any site'}.`)
+  console.log(`
+Deploy the folder to a domain that holds nothing else — a separate registrable domain, not a
+subdomain of your site — then embed a package:
+
+  <iframe src="https://<player domain>/?src=<package url>" allow="fullscreen"
+          style="width: 100%; border: 0"></iframe>
+  <script src="https://<player domain>/resizer.js"></script>
+
+_headers (Netlify, Cloudflare Pages) and vercel.json (Vercel) carry the policy and the caching.
+Other hosts, GitHub Pages among them, get the policy from the page itself${site.ancestors ? ', without --ancestors,\nwhich only a header can carry' : ''}.`)
+} catch (error) {
+  if (error instanceof EmbedError) {
+    console.error(`h5p-embed: ${error.message}`)
+    process.exit(1)
+  }
+  throw error
+}

package/lib/build.mjs

@@ -0,0 +1,231 @@
+import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Writes the embed page as a static site: one folder, deployable to any static host, that a site
+ * frames from a player domain of its own. Everything comes from installed packages — the element
+ * and its workers from the player's `dist/`, the H5P runtime from its own package as
+ * `frame-assets/`, the library pack from `@missing-elements/h5p-libraries` — so the versions are
+ * the ones this package was published with, and nothing is fetched.
+ */
+
+export class EmbedError extends Error {}
+
+const require = createRequire(import.meta.url)
+// `fileURLToPath` rather than `import.meta.dirname`, which Node 20 has only from 20.11.
+const SITE = fileURLToPath(new URL('../site', import.meta.url))
+
+/** The page's own files, copied as they are; `index.html` is written, not copied. */
+const PAGE_FILES = ['embed.js', 'embed.css', 'main.js', 'resizer.js']
+/** The player's files, by the names the element looks for beside itself. */
+const PLAYER_FILES = ['h5p-player.js', 'h5p-sw.js', 'h5p-jobs.js']
+
+/** Where an installed package's file is, or a message that says which one is missing. */
+function installed(specifier, hint) {
+  try {
+    return require.resolve(specifier)
+  } catch {
+    throw new EmbedError(`${specifier} is not installed or not built. ${hint}`)
+  }
+}
+
+/**
+ * An origin as the CSP and the page compare it: `https://host[:port]`, or plain http on a loopback
+ * address for trying it locally. Anything with a path, a query or a trailing slash is refused
+ * rather than trimmed, so a typo is not silently a different policy.
+ */
+export function parseOrigin(value) {
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new EmbedError(`Not an origin: ${value}. Write it as https://host.example`)
+  }
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+    throw new EmbedError(`Not an https origin: ${value}`)
+  }
+  if (url.origin !== value) throw new EmbedError(`Not an origin: ${value}. Write it as ${url.origin}, with no path or trailing slash`)
+  return url.origin
+}
+
+/** Origins given as a list, or as one string separated by commas or whitespace. */
+export function parseOrigins(values) {
+  if (values == null) return null
+  const list = (Array.isArray(values) ? values : [values]).flatMap((value) => String(value).split(/[\s,]+/)).filter(Boolean)
+  return [...new Set(list.map(parseOrigin))]
+}
+
+/**
+ * The page's policy. `connect-src` is where the element and its workers may fetch packages and
+ * library bundles from: any https host by default, which is what a player for links needs, or
+ * exactly the hosts given. `frame-ancestors` goes only into a header — a `<meta>` policy ignores
+ * it — and names who may frame the page; without it any site may.
+ */
+/**
+ * @param {object} [options]
+ * @param {string[] | null} [options.packages]
+ * @param {string[] | null} [options.ancestors]
+ * @param {boolean} [options.meta] for the page's `<meta>`, which cannot carry `frame-ancestors`
+ */
+export function contentSecurityPolicy({ packages = null, ancestors = null, meta = false } = {}) {
+  const directives = [
+    "default-src 'self'",
+    "script-src 'self'",
+    "style-src 'self'",
+    "img-src 'self' data: blob:",
+    "font-src 'self'",
+    `connect-src ${["'self'", ...(packages ?? ['https:'])].join(' ')}`,
+    "worker-src 'self' blob:",
+    "frame-src 'self'",
+    "object-src 'none'",
+    "base-uri 'self'",
+    "form-action 'self'"
+  ]
+  if (ancestors && !meta) directives.push(`frame-ancestors ${ancestors.join(' ')}`)
+  return directives.join('; ')
+}
+
+/** Header rules, one set for every host format: the policy everywhere, and the caching that matters. */
+function headerRules(csp) {
+  const revalidate = 'public, max-age=3600, stale-while-revalidate=86400'
+  return [
+    {
+      path: '/*',
+      headers: {
+        'Content-Security-Policy': csp,
+        'X-Content-Type-Options': 'nosniff',
+        'Referrer-Policy': 'strict-origin-when-cross-origin'
+      }
+    },
+    // The worker is checked on every load, so an update reaches learners on their next visit.
+    { path: '/h5p-sw.js', headers: { 'Cache-Control': 'no-cache' } },
+    { path: '/frame-assets/*', headers: { 'Cache-Control': revalidate } },
+    { path: '/resizer.js', headers: { 'Cache-Control': revalidate } },
+    { path: '/libraries.h5p', headers: { 'Cache-Control': revalidate } }
+  ]
+}
+
+/** Netlify's and Cloudflare Pages' `_headers`. */
+function netlifyHeaders(rules) {
+  return rules.map(({ path, headers }) => `${path}\n${Object.entries(headers).map(([key, value]) => `  ${key}: ${value}`).join('\n')}`).join('\n') + '\n'
+}
+
+/** Vercel's `vercel.json`, for deploying the folder as a project of its own. */
+function vercelConfig(rules) {
+  const source = (path) => (path === '/*' ? '/(.*)' : path.replace(/\*$/, '(.*)'))
+  return JSON.stringify(
+    { headers: rules.map(({ path, headers }) => ({ source: source(path), headers: Object.entries(headers).map(([key, value]) => ({ key, value })) })) },
+    null,
+    2
+  ) + '\n'
+}
+
+function notice({ version, libraries }) {
+  return `This folder is the H5P embed page, written by @missing-elements/h5p-embed.
+
+  index.html, main.js, embed.js, embed.css, resizer.js, config.js
+                    the embed page and the sizing script: MIT
+  h5p-player.js, h5p-sw.js, h5p-jobs.js
+                    @missing-elements/h5p-offline-player ${version}: MIT. The two workers also
+                    carry zip.js, BSD-3-Clause, its licence in each file's header.
+  frame-assets/     @missing-elements/h5p-runtime, the H5P core runtime: GPL-3.0-only. Its
+                    LICENSE.txt and NOTICE.txt say what it is and where its source is; keep them
+                    with it.
+${libraries ? `  libraries.h5p     @missing-elements/h5p-libraries, the H5P hub's libraries, each under its
+                    own licence, listed in libraries.txt.
+` : ''}
+Serve it from a domain that holds nothing else, and frame it:
+
+  <iframe src="https://<this domain>/?src=<package url>" allow="fullscreen"
+          style="width: 100%; border: 0"></iframe>
+  <script src="https://<this domain>/resizer.js"></script>
+
+https://github.com/missing-elements/h5p-offline-player/tree/main/packages/embed
+`
+}
+
+/** Whether a directory exists and has anything in it. A path that is a file is an error. */
+async function occupied(dir) {
+  let info
+  try {
+    info = await stat(dir)
+  } catch {
+    return false
+  }
+  if (!info.isDirectory()) throw new EmbedError(`${dir} is a file, not a folder.`)
+  return (await readdir(dir)).length > 0
+}
+
+/**
+ * Writes the site into `out`. Refuses a folder that already has files in it unless `force`, and
+ * even then only replaces the files it writes, so pointing it at the wrong folder costs nothing
+ * that was not its own.
+ *
+ * @param {object} options
+ * @param {string} options.out
+ * @param {boolean} [options.libraries] include the library pack, for `libraries=pack` (default true)
+ * @param {string[] | string | null} [options.packages] the only origins packages may come from
+ * @param {string[] | string | null} [options.ancestors] the only origins that may frame the page
+ * @param {boolean} [options.force]
+ */
+export async function buildSite({ out, libraries = true, packages = null, ancestors = null, force = false }) {
+  if (!out) throw new EmbedError('No output folder given.')
+  const target = resolve(out)
+  const allowedPackages = parseOrigins(packages)
+  const allowedAncestors = parseOrigins(ancestors)
+  if (allowedPackages?.length === 0) throw new EmbedError('--packages names no origin.')
+  if (allowedAncestors?.length === 0) throw new EmbedError('--ancestors names no origin.')
+  // Checked with --force too: a path that is a file is refused either way.
+  if ((await occupied(target)) && !force) {
+    throw new EmbedError(`${out} is not empty. Choose an empty folder, or pass --force to replace the files this writes.`)
+  }
+
+  const player = dirname(installed('@missing-elements/h5p-offline-player/dist/h5p-player.js', 'Run `pnpm build` in the workspace, or reinstall this package.'))
+  const runtime = dirname(installed('@missing-elements/h5p-runtime/dist/h5p.css', 'Run `pnpm build` in the workspace, or reinstall this package.'))
+  const pack = libraries ? installed('@missing-elements/h5p-libraries/libraries.h5p', 'Reinstall this package, or pass --no-libraries.') : null
+  const version = (await readFile(join(player, 'VERSION'), 'utf8').catch(() => 'unknown')).trim()
+
+  await mkdir(target, { recursive: true })
+  for (const name of PAGE_FILES) await cp(join(SITE, name), join(target, name))
+  for (const name of PLAYER_FILES) await cp(join(player, name), join(target, name))
+  await rm(join(target, 'frame-assets'), { recursive: true, force: true })
+  await cp(runtime, join(target, 'frame-assets'), { recursive: true })
+  if (pack) {
+    await cp(pack, join(target, 'libraries.h5p'))
+    await cp(join(dirname(pack), 'libraries.txt'), join(target, 'libraries.txt'))
+  } else {
+    await rm(join(target, 'libraries.h5p'), { force: true })
+    await rm(join(target, 'libraries.txt'), { force: true })
+  }
+
+  const html = await readFile(join(SITE, 'index.html'), 'utf8')
+  await writeFile(join(target, 'index.html'), html.replace('%CSP%', contentSecurityPolicy({ packages: allowedPackages, meta: true })))
+  await writeFile(
+    join(target, 'config.js'),
+    `// Written by h5p-embed: what main.js hands the page.\nexport default ${JSON.stringify({ libraries: Boolean(pack), packages: allowedPackages })}\n`
+  )
+
+  const csp = contentSecurityPolicy({ packages: allowedPackages, ancestors: allowedAncestors })
+  const rules = headerRules(csp)
+  await writeFile(join(target, '_headers'), netlifyHeaders(rules))
+  await writeFile(join(target, 'vercel.json'), vercelConfig(rules))
+  await writeFile(join(target, 'NOTICE.txt'), notice({ version, libraries: Boolean(pack) }))
+
+  return { out: target, version, csp, libraries: Boolean(pack), packages: allowedPackages, ancestors: allowedAncestors, size: await sizeOf(target) }
+}
+
+/**
+ * The folder's size in bytes, for the summary. Paths from a recursive `readdir` rather than
+ * `Dirent.parentPath`, which Node 20 has only from 20.12.
+ */
+async function sizeOf(dir) {
+  let total = 0
+  for (const name of await readdir(dir, { recursive: true })) {
+    const info = await stat(join(dir, name))
+    if (info.isFile()) total += info.size
+  }
+  return total
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@missing-elements/h5p-embed",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Self-hosted H5P embeds: writes the H5P embed page as a static site for a player domain of your own, then any site frames it with an iframe and one script line. No H5P server, no third-party service; optional allowlists for package hosts and embedding sites.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/missing-elements/h5p-offline-player.git",
+    "directory": "packages/embed"
+  },
+  "homepage": "https://github.com/missing-elements/h5p-offline-player/tree/main/packages/embed#readme",
+  "bugs": {
+    "url": "https://github.com/missing-elements/h5p-offline-player/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "h5p-embed": "./bin/h5p-embed.mjs"
+  },
+  "exports": {
+    ".": "./lib/build.mjs",
+    "./embed.js": "./site/embed.js",
+    "./embed.css": "./site/embed.css",
+    "./resizer.js": "./site/resizer.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "site"
+  ],
+  "keywords": [
+    "h5p",
+    "h5p-embed",
+    "h5p-self-hosted",
+    "h5p-player",
+    "iframe",
+    "embed",
+    "static-site",
+    "elearning",
+    "cli"
+  ],
+  "scripts": {
+    "test": "pnpm --filter @missing-elements/h5p-offline-player build && vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepack": "node -e \"require('node:fs').copyFileSync('../../LICENSE', 'LICENSE')\"",
+    "prepublishOnly": "pnpm typecheck && pnpm test"
+  },
+  "dependencies": {
+    "@missing-elements/h5p-libraries": "workspace:^",
+    "@missing-elements/h5p-offline-player": "workspace:^",
+    "@missing-elements/h5p-runtime": "workspace:^"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "playwright": "^1.50.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/site/embed.css

@@ -0,0 +1,84 @@
+/* The embeddable page: nothing of its own on screen but the element, so the embedding site's
+   layout is the layout. `flow-root` keeps the body's height honest for the size it reports. */
+html,
+body {
+  margin: 0;
+  padding: 0;
+  background: transparent;
+}
+
+body {
+  display: flow-root;
+  font: 15px/1.5 system-ui, -apple-system, 'Segoe UI', sans-serif;
+  color: #15171c;
+}
+
+h5p-player {
+  display: block;
+}
+
+.notice {
+  margin: 0;
+  padding: 0.9rem 1.1rem;
+  border: 1px solid #e2e6ec;
+  border-radius: 10px;
+  background: #f6f8fa;
+}
+
+.notice.error {
+  border-color: #f0c2c5;
+  background: #fdf2f3;
+  color: #8f1b22;
+}
+
+.notice a {
+  color: inherit;
+  font-weight: 600;
+}
+
+.notice button {
+  margin-left: 0.5rem;
+  padding: 0.35rem 0.8rem;
+  border: 1px solid currentColor;
+  border-radius: 6px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+/* The element draws nothing until it is ready, and the first seconds go to registering the worker
+   and probing the package. The loader is in the HTML, so it shows before any script has run. */
+.loader {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.7rem;
+  min-height: 160px;
+  color: #5b6472;
+}
+
+.loader[hidden] {
+  display: none;
+}
+
+.spinner {
+  width: 1.4rem;
+  height: 1.4rem;
+  border: 3px solid #d9dee6;
+  border-top-color: #4a5568;
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation-duration: 2.4s;
+  }
+}

package/site/embed.js

@@ -0,0 +1,279 @@
+/*! @missing-elements/h5p-embed. MIT. */
+/**
+ * The embed page: the element alone, driven by the query string, for a site that puts a player
+ * domain of its own in an iframe. `startEmbed()` runs it; the page's `main.js` calls it with what
+ * `h5p-embed` was told when it wrote the site, and the demo's `/embed` with the demo's copy of the
+ * library pack.
+ *
+ *   ?src=<package url>[&libraries=pack|hub|<url> …][&preload=auto][&xapi=<parent origin>]
+ *    [&frame][&copyright][&export][&icon][&reporting][&fullscreen=off]
+ *    [&activity-id=<IRI>][&custom-css=<stylesheet url>]
+ *
+ * Upward it speaks H5P's own resizer protocol — the `hello` / `resize` exchange that h5p.org's
+ * embed code and its `h5p-resizer.js` use — so a page that already resizes h5p.org iframes
+ * resizes this one without a change, and any other page gets `resizer.js` from this origin. xAPI
+ * statements are relayed to the parent only when `xapi=` names the parent's origin, and they are
+ * posted to that origin only.
+ */
+
+/** Where `libraries=hub` fetches from: the one hub host that sends CORS headers (see the player). */
+const HUB_ORIGIN = 'https://api.h5p.org'
+
+/**
+ * @param {object} [options]
+ * @param {string | null} [options.librariesPack] the URL of a copy of `@missing-elements/h5p-libraries`
+ *   on this site, which `libraries=pack` names; without one, `pack` is refused
+ * @param {string[] | null} [options.packages] the origins packages and library bundles may come
+ *   from, besides this page's own; `null` plays any, asking first when the storage is this origin's
+ */
+export function startEmbed({ librariesPack = null, packages = null } = {}) {
+  const params = new URLSearchParams(location.search)
+  const player = document.querySelector('h5p-player')
+  const notice = document.querySelector('#notice')
+  const loader = document.querySelector('#loader')
+  const framed = window.parent !== window
+
+  /* ---------------------------------------------------------------- notices */
+
+  const say = (text, kind = '', link = null) => {
+    notice.replaceChildren()
+    if (text) {
+      notice.append(text)
+      if (link) {
+        const anchor = document.createElement('a')
+        anchor.href = link.href
+        anchor.target = '_top'
+        anchor.rel = 'noopener'
+        anchor.textContent = link.text
+        notice.append(' ', anchor, '.')
+      }
+    }
+    notice.className = `notice ${kind}`.trim()
+    notice.hidden = !text
+    requestAnimationFrame(announce)
+  }
+
+  const refuse = (text) => {
+    loader.hidden = true
+    say(text, 'error')
+  }
+
+  /* ---------------------------------------------------------------- sizing, upward */
+
+  /** The parent hears about the height in the shape h5p-resizer.js expects. Nothing in it is secret. */
+  const post = (message, target = '*') => {
+    if (framed) window.parent.postMessage(message, target)
+  }
+
+  // The body's own height rather than the document's scrollHeight: the latter can never report
+  // less than the frame, so a shrink would never be seen.
+  const contentHeight = () => Math.ceil(document.body.getBoundingClientRect().height)
+
+  const announce = () => post({ context: 'h5p', action: 'resize', scrollHeight: contentHeight() })
+
+  window.addEventListener('message', (event) => {
+    if (event.source !== window.parent || !event.data || event.data.context !== 'h5p') return
+    switch (event.data.action) {
+      case 'ready':
+        // h5p-resizer.js announces itself once it is on the page; it expects a `hello` back.
+        post({ context: 'h5p', action: 'hello' })
+        break
+      case 'hello':
+        announce()
+        break
+      case 'resizePrepared':
+        announce()
+        break
+    }
+  })
+
+  post({ context: 'h5p', action: 'hello' })
+
+  // The element dispatches `resize` before it applies the height to itself; measure after layout.
+  player.addEventListener('resize', () => requestAnimationFrame(announce))
+  player.addEventListener('ready', () => requestAnimationFrame(announce))
+
+  /* ---------------------------------------------------------------- xAPI, relayed on request */
+
+  /** An origin, or nothing: the parameter has to be exactly what `event.origin` will read. */
+  const originOf = (value) => {
+    if (!value) return null
+    try {
+      const origin = new URL(value).origin
+      return origin !== 'null' && origin === value.replace(/\/$/, '') ? origin : null
+    } catch {
+      return null
+    }
+  }
+
+  const relayTo = originOf(params.get('xapi'))
+  if (relayTo && framed) {
+    for (const type of ['xapi', 'finished']) {
+      player.addEventListener(type, (event) => {
+        post({ context: 'h5p-offline-player', action: type, ...event.detail }, relayTo)
+      })
+    }
+  }
+
+  /* ---------------------------------------------------------------- errors, and Safari */
+
+  player.addEventListener('error', (event) => {
+    const { code, message } = event.detail
+    if (code === 'no-worker' && framed) {
+      // Detected, not sniffed: a browser, an in-app one or a page that is not https may give a
+      // frame no Service Worker, and the player cannot run without one. Safari does allow it.
+      say("This browser does not run the player inside another site's page.", 'error', {
+        href: location.href,
+        text: 'Open it on its own'
+      })
+      return
+    }
+    // Once the content is up, a runtime error inside it is the content's business: it keeps
+    // running, and a red notice over a working video would say otherwise.
+    if (code === 'runtime' && player.state === 'ready') {
+      console.warn(`h5p-player: the content reported an error and kept running: ${message}`)
+      return
+    }
+    say(message || code, 'error')
+  })
+
+  player.addEventListener('statechange', (event) => {
+    const { state } = event.detail
+    if (state !== 'error') say('')
+    // Shown from the HTML on, until the content is up or the load has failed.
+    loader.hidden = state === 'ready' || state === 'error' || state === 'idle'
+    requestAnimationFrame(announce)
+  })
+
+  /* ---------------------------------------------------------------- which hosts */
+
+  /** The origin of a URL as this page resolves it, or `null` for what is not one. */
+  const urlOrigin = (value) => {
+    try {
+      const url = new URL(value, location.href)
+      // A `data:` or `blob:` URL has an opaque origin: name its scheme, so it is never "ours".
+      return url.origin === 'null' ? url.protocol : url.origin
+    } catch {
+      return null
+    }
+  }
+
+  const allowed = packages ? new Set(packages) : null
+  /** Whether this player was told it may fetch from `origin`. Always true without a list. */
+  const permitted = (origin) => origin === location.origin || !allowed || allowed.has(origin)
+
+  /**
+   * The `libraries` value with `pack` resolved to this site's copy, or an error to show. With a
+   * list of hosts, every bundle's origin has to be on it, the hub's included; the CSP that
+   * `h5p-embed` wrote says the same, this only says it in words.
+   */
+  const librarySources = (value) => {
+    const sources = []
+    for (const token of value.split(/\s+/).filter(Boolean)) {
+      if (token === 'pack') {
+        // The pack, with the hub behind it for what it lacks, where the hub may be reached: an
+        // export without its libraries then plays with no request to h5p.org in the common case.
+        // A site set up without the pack falls back to the hub alone, so a snippet written for
+        // `pack` keeps playing after a rebuild with --no-libraries.
+        if (librariesPack) sources.push(librariesPack)
+        if (permitted(HUB_ORIGIN)) sources.push('hub')
+        else if (!librariesPack) return { error: 'This player was set up without the library pack, so libraries=pack is not available here.' }
+      } else if (token === 'hub') {
+        if (!permitted(HUB_ORIGIN)) return { error: 'This player does not fetch libraries from the H5P hub.' }
+        sources.push(token)
+      } else {
+        const origin = urlOrigin(token)
+        if (!origin || !permitted(origin)) return { error: `This player does not fetch libraries from ${origin ?? token}.` }
+        sources.push(token)
+      }
+    }
+    return { value: [...new Set(sources)].join(' ') }
+  }
+
+  /**
+   * The element's display options, by their attribute names, for the embedding page to ask for:
+   * `&frame&copyright&export` shows H5P's action bar with those buttons, `&fullscreen=off` takes
+   * that one away, `&activity-id=` names the statements' object and `&custom-css=` restyles the
+   * content to the embedding site's taste. Not `custom-js`, `embed-code` or `user`: a script is
+   * a capability on this origin that a link should not hand out, the embed is the embed, and a
+   * learner's name has no place in a URL.
+   */
+  const applyOptions = () => {
+    for (const name of ['frame', 'copyright', 'export', 'icon', 'reporting']) {
+      if (params.has(name) && params.get(name) !== 'off') player.setAttribute(name, '')
+    }
+    if (params.get('fullscreen') === 'off') player.setAttribute('fullscreen', 'off')
+    for (const name of ['activity-id', 'custom-css']) {
+      const value = params.get(name)?.trim()
+      if (value) player.setAttribute(name, value)
+    }
+  }
+
+  const start = (value, libraries) => {
+    if (libraries) player.setAttribute('libraries', libraries)
+    if (params.get('preload') === 'auto') player.setAttribute('preload', 'auto')
+    applyOptions()
+    player.setAttribute('src', value)
+  }
+
+  /**
+   * Whether this document's storage is this origin's own: top level, or framed by this origin. A
+   * package's scripts run with the storage of the origin it plays on. In another site's frame
+   * that storage is partitioned by the embedding site, so a page can only ever reach what was
+   * played under its own embed; opened on its own, a link to a package from elsewhere waits for
+   * a click.
+   */
+  const sharesOriginStorage = () => {
+    if (!framed) return true
+    try {
+      return window.parent.location.origin === location.origin
+    } catch {
+      return false // Another origin's frame: reading its location throws, and the storage is partitioned.
+    }
+  }
+
+  /* ---------------------------------------------------------------- load */
+
+  const src = params.get('src')?.trim()
+  if (!src) {
+    refuse('No package given. Add ?src=<url of a .h5p file> to the address.')
+    return
+  }
+  const origin = urlOrigin(src)
+  if (!origin) {
+    refuse('The package address is not a URL.')
+    return
+  }
+  if (!permitted(origin)) {
+    refuse(`This player does not play packages from ${origin}.`)
+    return
+  }
+  const libraries = params.get('libraries')?.trim()
+  const sources = libraries ? librarySources(libraries) : { value: '' }
+  if (sources.error) {
+    refuse(sources.error)
+    return
+  }
+
+  // A host on the list was vouched for when the site was set up; anything else from another
+  // origin waits for a click when it would share this origin's storage.
+  if (origin === location.origin || allowed || !sharesOriginStorage()) {
+    start(src, sources.value)
+    return
+  }
+  loader.hidden = true
+  const host = new URL(src, location.href).host || origin
+  const button = document.createElement('button')
+  button.type = 'button'
+  button.textContent = 'Open the package'
+  button.addEventListener('click', () => {
+    say('')
+    loader.hidden = false
+    start(src, sources.value)
+  })
+  say(
+    `This link opens a package from ${host}. A package runs its own scripts on this site, and they ` +
+      'can read what other packages saved in this browser. Open it only if you trust that site.'
+  )
+  notice.append(' ', button)
+}

package/site/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta http-equiv="Content-Security-Policy" content="%CSP%" />
+    <meta name="robots" content="noindex" />
+    <title>H5P player</title>
+    <link rel="stylesheet" href="./embed.css" />
+    <script type="module" src="./h5p-player.js"></script>
+    <script type="module" src="./main.js"></script>
+  </head>
+
+  <body>
+    <div class="loader" id="loader" role="status">
+      <span class="spinner" aria-hidden="true"></span>
+      <span class="loader-text">Loading…</span>
+    </div>
+    <h5p-player auto-resize></h5p-player>
+    <p class="notice" id="notice" hidden></p>
+  </body>
+</html>

package/site/main.js

@@ -0,0 +1,10 @@
+/*! @missing-elements/h5p-embed. MIT. */
+// The page's entry: `config.js` is what `h5p-embed` was told when it wrote this site — whether
+// the library pack is here, and which hosts packages may come from.
+import config from './config.js'
+import { startEmbed } from './embed.js'
+
+startEmbed({
+  librariesPack: config.libraries ? new URL('./libraries.h5p', import.meta.url).href : null,
+  packages: config.packages
+})

package/site/resizer.js

@@ -0,0 +1,61 @@
+/*! h5p-offline-player resizer. MIT. Sizes an <iframe> of the H5P embed page to its content. */
+/**
+ * The page-side half of H5P's resizer protocol, for a page that frames the embed page
+ * (`@missing-elements/h5p-embed`). The frame can only report its height upward, by
+ * `postMessage`, and something on the page has to apply it:
+ * this script, in one line, or h5p.org's own `h5p-resizer.js`, which speaks the same protocol.
+ * This one is served from the player's origin, so an embedding page sends nothing to a third
+ * party and does not depend on a path on h5p.org.
+ *
+ *   <script src="https://<player origin>/resizer.js"></script>
+ *
+ * It answers every frame on the page that speaks the protocol, which is also what h5p.org's
+ * script does: a frame can only ever ask for the height of itself. Classic script, no module,
+ * so it runs wherever an embed block runs.
+ */
+(function () {
+  if (window.__h5pResizer) return;
+  window.__h5pResizer = true;
+
+  var frameOf = function (source) {
+    var frames = document.getElementsByTagName('iframe');
+    for (var i = 0; i < frames.length; i++) {
+      if (frames[i].contentWindow === source) return frames[i];
+    }
+    return null;
+  };
+
+  window.addEventListener('message', function (event) {
+    var data = event.data;
+    if (!data || data.context !== 'h5p' || !event.source) return;
+    var frame = frameOf(event.source);
+    if (!frame) return;
+    switch (data.action) {
+      case 'hello':
+        // The frame asks whether anyone is listening; the reply makes it start reporting.
+        event.source.postMessage({ context: 'h5p', action: 'hello' }, event.origin);
+        break;
+      case 'prepareResize':
+        // The frame is about to measure itself; it wants the box no larger than its content.
+        if (typeof data.scrollHeight === 'number' && frame.clientHeight !== data.scrollHeight) {
+          frame.style.height = data.scrollHeight + 'px';
+        }
+        event.source.postMessage({ context: 'h5p', action: 'resizePrepared' }, event.origin);
+        break;
+      case 'resize':
+        if (typeof data.scrollHeight === 'number') frame.style.height = data.scrollHeight + 'px';
+        break;
+    }
+  });
+
+  // A frame that loaded before this script said its hello to nobody; tell every frame the
+  // listener is here, and the ones that speak the protocol say hello again.
+  var announce = function () {
+    var frames = document.getElementsByTagName('iframe');
+    for (var i = 0; i < frames.length; i++) {
+      try { frames[i].contentWindow.postMessage({ context: 'h5p', action: 'ready' }, '*'); } catch (e) { /* not ours */ }
+    }
+  };
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', announce);
+  else announce();
+})();