@missing-elements/h5p-embed 1.0.1 → 1.1.1

package/README.md

@@ -3,8 +3,11 @@
 Writes the H5P embed page as a static site for a player domain of your own. Any site then embeds
 a package with an iframe and one script line. No H5P server, no backend, no third-party service.
 
+Needs Node 22 or later. Write `@latest`: without it, npm on an older Node quietly installs the
+last version that supported it, which writes a player from before 1.0.
+
 ```bash
-npx @missing-elements/h5p-embed h5p-player     # the folder defaults to ./h5p-player
+npx @missing-elements/h5p-embed@latest h5p-player     # the folder defaults to ./h5p-player
 ```
 
 Deploy it to any static host, then embed:
@@ -27,7 +30,7 @@ a subdomain shares your site's cookies.
 
 | Option | Effect |
 |---|---|
-| `--packages <origins>` | Play packages and fetch library bundles only from these origins (the site's own is always allowed). Add `https://cdn.jsdelivr.net` for `libraries=pack` on a site built with `--no-libraries`. Default: any https host |
+| `--packages <origins>` | Play packages and fetch library bundles only from these origins (the site's own is always allowed). Each host on its own, with no wildcard: the page compares exact origins. Add `https://cdn.jsdelivr.net` for `libraries=pack` on a site built with `--no-libraries`. Default: any https host |
 | `--ancestors <origins>` | Only these sites may frame the page (`frame-ancestors`, header only). Default: any site |
 | `--default-libraries <sources>` | The `libraries` value for addresses that name none: `pack` or URLs. Checked against `--packages`. Default: none, so exports without libraries are refused unless the address asks |
 | `--no-libraries` | Leave out the library pack, 13.8 MB in `libraries/`, one archive per library, of which a learner's browser fetches only those a package needs; `libraries=pack` then fetches them from jsDelivr, where allowed |
@@ -40,7 +43,7 @@ through:** the browser's policy applies to each hop, and a redirect off the list
 network error.
 
 ```bash
-npx @missing-elements/h5p-embed h5p-player \
+npx @missing-elements/h5p-embed@latest h5p-player \
   --packages https://cdn.example.org \
   --ancestors "https://www.example.org https://lms.example.org"
 ```
@@ -74,7 +77,7 @@ To update, run the command again with `--force` and redeploy.
 
 | Parameter | Effect |
 |---|---|
-| `src=<url>` | The package, required. Encode `&`, `#`, `+`, `%` and spaces |
+| `src=<url>` | The package, required: an `http` or `https` URL, or a path on the player domain. Encode `&`, `#`, `+`, `%` and spaces |
 | `libraries=pack`, `<url>` or `none` | Where libraries come from; several are tried in order. `pack` is this domain's copy, or jsDelivr's without one: a package gets the libraries it lacks from it, and those it carries at the pack's newer versions. `none` turns off `--default-libraries` |
 | `refresh-libraries=off` | Play the libraries a package carries as exported; `pack` then only fills gaps |
 | `frame`, `copyright`, `export`, `icon`, `reporting` | H5P's action bar and its buttons |
@@ -82,7 +85,7 @@ To update, run the command again with `--force` and redeploy.
 | `preload=auto` | Start fetching media at once |
 | `activity-id=<IRI>` | The xAPI object id, instead of the package URL |
 | `custom-css=<url>` | A stylesheet loaded into the content |
-| `lang=<tag>` | The language of H5P's own buttons and dialogs, such as `de` or `pt-BR`. Default: English |
+| `lang=<tag>` | The language of H5P's own buttons and dialogs, such as `de` or `pt-BR`, for a package that does not name its own. A package that names its language in `h5p.json` gets them in that language, matching its content. Default: English |
 | `xapi=<origin>` | Relay statements to the embedding page |
 
 A custom script and a learner's name cannot be set on the address. Opened unframed, the page plays
@@ -135,6 +138,7 @@ export, which `libraries=pack` then plays from) or `packBase` (the folder of a c
 `@missing-elements/h5p-runtime` export, for a bundled element) and `askInOwnFrame` (default
 `true`; `false` plays a package from another origin as it is when a same-origin page frames it).
 `librariesPack`, the URL of a whole `libraries.h5p`, still works, as a bundle that only fills gaps.
+Both entries ship with TypeScript declarations.
 
 ```js
 import '@missing-elements/h5p-offline-player'

package/lib/build.mjs

@@ -23,7 +23,11 @@ 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. */
+/**
+ * Where an installed package's file is, or a message that says which one is missing.
+ * @param {string} specifier
+ * @param {string} hint
+ */
 function installed(specifier, hint) {
   try {
     return require.resolve(specifier)
@@ -35,7 +39,13 @@ function installed(specifier, 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.
+ * rather than trimmed, so a typo is not silently a different policy. The host is held to what a
+ * CSP host is, letters, digits and hyphens between dots: the URL parser takes `*`, `;` and `"` in
+ * a host, and a wildcard would allow what the page then refuses, by exact origin, on every load,
+ * while a quote would end the policy in the files that quote it (#58).
+ * @internal
+ * @param {string} value
+ * @returns {string}
  */
 export function parseOrigin(value) {
   let url
@@ -48,6 +58,9 @@ export function parseOrigin(value) {
   if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
     throw new EmbedError(`Not an https origin: ${value}`)
   }
+  if (!loopback && !/^[a-z0-9-]+(?:\.[a-z0-9-]+)*$/.test(url.hostname)) {
+    throw new EmbedError(`Not an origin: ${value}. A host is letters, digits, hyphens and dots, and each host is listed on its own, with no wildcard`)
+  }
   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
 }
@@ -59,6 +72,7 @@ const PACK_CDN_ORIGIN = 'https://cdn.jsdelivr.net'
  * A `libraries` value for addresses that name none, checked against the site it goes into: the
  * tokens the page understands (`pack`, `none`, https URLs), and with a host list, nothing
  * the page would then refuse on every load. Returns the value normalised to single spaces.
+ * @internal
  *
  * @param {string | null | undefined} value
  * @param {object} [site]
@@ -97,7 +111,12 @@ export function parseDefaultLibraries(value, { packages = null, libraries = true
   return tokens.join(' ')
 }
 
-/** Origins given as a list, or as one string separated by commas or whitespace. */
+/**
+ * Origins given as a list, or as one string separated by commas or whitespace.
+ * @internal
+ * @param {string[] | string | null | undefined} values
+ * @returns {string[] | null}
+ */
 export function parseOrigins(values) {
   if (values == null) return null
   const list = (Array.isArray(values) ? values : [values]).flatMap((value) => String(value).split(/[\s,]+/)).filter(Boolean)
@@ -111,6 +130,7 @@ export function parseOrigins(values) {
  * it — and names who may frame the page; without it any site may.
  */
 /**
+ * @internal
  * @param {object} [options]
  * @param {string[] | null} [options.packages]
  * @param {string[] | null} [options.ancestors]
@@ -134,7 +154,11 @@ export function contentSecurityPolicy({ packages = null, ancestors = null, meta
   return directives.join('; ')
 }
 
-/** Header rules, one set for every host format: the policy everywhere, and the caching that matters. */
+/**
+ * Header rules, one set for every host format: the policy everywhere, and the caching that matters.
+ * @param {string} csp
+ * @returns {{ path: string, headers: Record<string, string> }[]}
+ */
 function headerRules(csp) {
   const revalidate = 'public, max-age=3600, stale-while-revalidate=86400'
   // Asked again on every load, a 304 when nothing changed. The runtime's files keep their names
@@ -161,13 +185,20 @@ function headerRules(csp) {
   ]
 }
 
-/** Netlify's and Cloudflare Pages' `_headers`. */
+/**
+ * Netlify's and Cloudflare Pages' `_headers`.
+ * @param {ReturnType<typeof headerRules>} rules
+ */
 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. */
+/**
+ * Vercel's `vercel.json`, for deploying the folder as a project of its own.
+ * @param {ReturnType<typeof headerRules>} rules
+ */
 function vercelConfig(rules) {
+  /** @param {string} path */
   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 })) })) },
@@ -184,13 +215,19 @@ function vercelConfig(rules) {
  * in every format, which is safe because the policy carries only single quotes.
  */
 
-/** The rule for every path, and the ones for a single path or prefix. */
+/**
+ * The rule for every path, and the ones for a single path or prefix.
+ * @param {ReturnType<typeof headerRules>} rules
+ */
 function splitRules(rules) {
-  const all = rules.find((rule) => rule.path === '/*')
+  const all = /** @type {ReturnType<typeof headerRules>[number]} */ (rules.find((rule) => rule.path === '/*'))
   return { all, specific: rules.filter((rule) => rule !== all) }
 }
 
-/** Caddy's `Caddyfile`: a site block to run as it is, or to paste into one. */
+/**
+ * Caddy's `Caddyfile`: a site block to run as it is, or to paste into one.
+ * @param {ReturnType<typeof headerRules>} rules
+ */
 function caddyfile(rules) {
   const { all, specific } = splitRules(rules)
   const lines = [
@@ -210,10 +247,13 @@ function caddyfile(rules) {
  * nginx: a file to `include` inside the `server` block that serves the folder. nginx's
  * `add_header` in a `location` replaces every `add_header` inherited from the server level
  * rather than adding to it, so each location repeats the headers that apply everywhere.
+ * @param {ReturnType<typeof headerRules>} rules
  */
 function nginxConf(rules) {
   const { all, specific } = splitRules(rules)
+  /** @param {[string, string]} entry */
   const header = ([key, value]) => `add_header ${key} "${value}" always;`
+  /** @param {string} path */
   const matcher = (path) => (path.endsWith('/*') ? `^~ ${path.slice(0, -1)}` : `= ${path}`)
   const lines = [
     '# Written by h5p-embed. Include this file inside the server block that serves the folder:',
@@ -229,10 +269,15 @@ function nginxConf(rules) {
   return lines.join('\n') + '\n'
 }
 
-/** Apache's `.htaccess`, for a folder under a vhost that allows it. */
+/**
+ * Apache's `.htaccess`, for a folder under a vhost that allows it.
+ * @param {ReturnType<typeof headerRules>} rules
+ */
 function htaccess(rules) {
   const { all, specific } = splitRules(rules)
+  /** @param {[string, string]} entry */
   const header = ([key, value]) => `Header always set ${key} "${value}"`
+  /** @param {ReturnType<typeof headerRules>[number]} rule */
   const block = ({ path, headers }) => {
     const body = Object.entries(headers).map((entry) => `\t${header(entry)}`).join('\n')
     // <Files> matches a name in any directory; a prefix needs the request URI, with no anchor at
@@ -250,6 +295,7 @@ function htaccess(rules) {
   return lines.join('\n') + '\n'
 }
 
+/** @param {{ version: string, libraries: boolean }} site */
 function notice({ version, libraries }) {
   return `This folder is the H5P embed page, written by @missing-elements/h5p-embed.
 
@@ -277,7 +323,10 @@ 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. */
+/**
+ * Whether a directory exists and has anything in it. A path that is a file is an error.
+ * @param {string} dir
+ */
 async function occupied(dir) {
   let info
   try {
@@ -289,6 +338,19 @@ async function occupied(dir) {
   return (await readdir(dir)).length > 0
 }
 
+/**
+ * What `buildSite` wrote, for a summary.
+ * @typedef {object} BuiltSite
+ * @property {string} out the folder, as an absolute path
+ * @property {string} version the player's version, as its `dist/VERSION` says
+ * @property {string} csp the policy the headers carry
+ * @property {boolean} libraries whether the site carries the library pack's parts
+ * @property {string[] | null} packages the origins packages may come from; `null` for any
+ * @property {string[] | null} ancestors the origins that may frame the page; `null` for any
+ * @property {string | null} defaultLibraries the `libraries` value for addresses that name none
+ * @property {number} size the folder's size in bytes
+ */
+
 /**
  * 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
@@ -301,6 +363,7 @@ async function occupied(dir) {
  * @param {string[] | string | null} [options.ancestors] the only origins that may frame the page
  * @param {string | null} [options.defaultLibraries] the `libraries` value for addresses that name none
  * @param {boolean} [options.force]
+ * @returns {Promise<BuiltSite>}
  */
 export async function buildSite({ out, libraries = true, packages = null, ancestors = null, defaultLibraries = null, force = false }) {
   if (!out) throw new EmbedError('No output folder given.')
@@ -366,6 +429,7 @@ export async function buildSite({ out, libraries = true, packages = null, ancest
 /**
  * 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.
+ * @param {string} dir
  */
 async function sizeOf(dir) {
   let total = 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@missing-elements/h5p-embed",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "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": {
@@ -20,8 +20,14 @@
     "h5p-embed": "./bin/h5p-embed.mjs"
   },
   "exports": {
-    ".": "./lib/build.mjs",
-    "./embed.js": "./site/embed.js",
+    ".": {
+      "types": "./types/lib/build.d.mts",
+      "default": "./lib/build.mjs"
+    },
+    "./embed.js": {
+      "types": "./types/site/embed.d.ts",
+      "default": "./site/embed.js"
+    },
     "./embed.css": "./site/embed.css",
     "./resizer.js": "./site/resizer.js",
     "./package.json": "./package.json"
@@ -29,7 +35,8 @@
   "files": [
     "bin",
     "lib",
-    "site"
+    "site",
+    "types"
   ],
   "keywords": [
     "h5p",
@@ -44,21 +51,22 @@
   ],
   "dependencies": {
     "@missing-elements/h5p-libraries": "^1.0.0",
-    "@missing-elements/h5p-offline-player": "^1.0.1",
-    "@missing-elements/h5p-runtime": "^1.0.0"
+    "@missing-elements/h5p-runtime": "^1.0.0",
+    "@missing-elements/h5p-offline-player": "^1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",
-    "@zip.js/zip.js": "^2.23.0",
-    "playwright": "^1.64.0",
+    "@zip.js/zip.js": "^2.24.0",
+    "playwright": "^1.64.1",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.5"
   },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
     "test": "pnpm --filter @missing-elements/h5p-offline-player build && vitest run",
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "pnpm types && tsc -p tsconfig.json",
+    "types": "node -e \"require('node:fs').rmSync('types', { recursive: true, force: true })\" && tsc -p tsconfig.types.json"
   }
 }

package/site/embed.js

@@ -18,6 +18,10 @@
  * package shows under its preview.
  */
 
+/**
+ * @import { H5PPlayerElement, PlayerErrorDetail, PlayerStateChangeDetail, ReadyDetail } from '@missing-elements/h5p-offline-player'
+ */
+
 /** Where the element's `libraries="pack"` fetches the library pack from, for a site without its own copy. */
 const PACK_CDN_ORIGIN = 'https://cdn.jsdelivr.net'
 
@@ -25,7 +29,7 @@ const PACK_CDN_ORIGIN = 'https://cdn.jsdelivr.net'
  * @param {object} [options]
  * @param {string | null} [options.packBase] the folder of this site's copy of the library pack's
  *   parts (`parts/` of `@missing-elements/h5p-libraries`), which `libraries=pack` plays from
- * @param {{ libraries: object[] } | null} [options.pack] the same, as the `pack` export a bundler
+ * @param {H5PPlayerElement['pack']} [options.pack] the same, as the `pack` export a bundler
  *   resolves; it wins over `packBase`. Without either, `pack` is the element's copy on jsDelivr
  * @param {string | null} [options.librariesPack] the URL of a whole `libraries.h5p` on this site,
  *   for a page written before the pack was split: played as any bundle, with no refresh
@@ -35,7 +39,7 @@ const PACK_CDN_ORIGIN = 'https://cdn.jsdelivr.net'
  * @param {string | null} [options.defaultLibraries] the `libraries` value for an address that has
  *   none — `pack` or URLs, as the parameter — so a snippet without `&libraries=` still plays
  *   an export that carries no libraries; `&libraries=none` turns it off for one address
- * @param {object | null} [options.runtime] the `runtime` export of `@missing-elements/h5p-runtime`,
+ * @param {H5PPlayerElement['runtime']} [options.runtime] the `runtime` export of `@missing-elements/h5p-runtime`,
  *   for a page that bundles the element; without it the element looks for `frame-assets/` beside itself
  * @param {boolean} [options.askInOwnFrame] whether a package from another origin plays `untrusted`,
  *   with a click to play it with its own code when it needs that, when this page is framed by a
@@ -44,19 +48,24 @@ const PACK_CDN_ORIGIN = 'https://cdn.jsdelivr.net'
  */
 export function startEmbed({ packBase = null, pack = null, librariesPack = null, packages = null, defaultLibraries = null, runtime = null, askInOwnFrame = true } = {}) {
   const params = new URLSearchParams(location.search)
-  const player = document.querySelector('h5p-player')
+  const player = /** @type {H5PPlayerElement} */ (document.querySelector('h5p-player'))
   // Before `src`: the element resolves the runtime's files, and reads where the pack is, when a
   // package is set.
   if (runtime) player.runtime = runtime
   if (pack) player.pack = pack
   else if (packBase) player.setAttribute('pack-base', packBase)
   const ownPack = Boolean(pack || packBase)
-  const notice = document.querySelector('#notice')
-  const loader = document.querySelector('#loader')
+  const notice = /** @type {HTMLElement} */ (document.querySelector('#notice'))
+  const loader = /** @type {HTMLElement} */ (document.querySelector('#loader'))
   const framed = window.parent !== window
 
   /* ---------------------------------------------------------------- notices */
 
+  /**
+   * @param {string} text
+   * @param {string} [kind]
+   * @param {{ href: string, text: string } | null} [link]
+   */
   const say = (text, kind = '', link = null) => {
     notice.replaceChildren()
     if (text) {
@@ -75,6 +84,10 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
     requestAnimationFrame(announce)
   }
 
+  /**
+   * @param {string} text
+   * @param {string} [code]
+   */
   const refuse = (text, code = 'refused') => {
     loader.hidden = true
     say(text, 'error')
@@ -87,6 +100,8 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
    * A message to the page that frames this one: the height in the shape h5p-resizer.js expects,
    * and `report`, `error` and `xapi` in this page's own. To any parent unless a target is named,
    * since nothing in the height is secret; the xAPI relay names the origin that opted in.
+   * @param {object} message
+   * @param {string} [target]
    */
   const post = (message, target = '*') => {
     if (framed) window.parent.postMessage(message, target)
@@ -139,7 +154,7 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
   let startedAt = 0
 
   player.addEventListener('ready', (event) => {
-    const { source, metadata, libraryBundle } = event.detail
+    const { source, metadata, libraryBundle } = /** @type {CustomEvent<ReadyDetail>} */ (event).detail
     post({
       context: 'h5p-offline-player',
       action: 'report',
@@ -158,7 +173,10 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
 
   /* ---------------------------------------------------------------- xAPI, relayed on request */
 
-  /** An origin, or nothing: the parameter has to be exactly what `event.origin` will read. */
+  /**
+   * An origin, or nothing: the parameter has to be exactly what `event.origin` will read.
+   * @param {string | null} value
+   */
   const originOf = (value) => {
     if (!value) return null
     try {
@@ -173,18 +191,22 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
   if (relayTo && framed) {
     for (const type of ['xapi', 'finished']) {
       player.addEventListener(type, (event) => {
-        post({ context: 'h5p-offline-player', action: type, ...event.detail }, relayTo)
+        post({ context: 'h5p-offline-player', action: type, .../** @type {CustomEvent<object>} */ (event).detail }, relayTo)
       })
     }
   }
 
   /* ---------------------------------------------------------------- errors, and Safari */
 
-  /** Asks whether to play an untrusted package with its own code; set when one is played so. */
+  /**
+   * Asks whether to play an untrusted package with its own code; set when one is played so.
+   * @type {(() => void) | null}
+   */
   let askToTrust = null
 
   player.addEventListener('error', (event) => {
-    const { code, message, missingLibraries } = event.detail
+    // The element's own `error`, which the DOM's types take for a script's `ErrorEvent`.
+    const { code, message, missingLibraries } = /** @type {CustomEvent<PlayerErrorDetail>} */ (/** @type {unknown} */ (event)).detail
     // Played untrusted, it cannot do without its own copy of a library: a click decides.
     if (missingLibraries?.carried && player.untrusted && askToTrust) {
       askToTrust()
@@ -211,7 +233,7 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
   })
 
   player.addEventListener('statechange', (event) => {
-    const { state } = event.detail
+    const { state } = /** @type {CustomEvent<PlayerStateChangeDetail>} */ (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'
@@ -220,7 +242,10 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
 
   /* ---------------------------------------------------------------- which hosts */
 
-  /** The origin of a URL as this page resolves it, or `null` for what is not one. */
+  /**
+   * The origin of a URL as this page resolves it, or `null` for what is not one.
+   * @param {string} value
+   */
   const urlOrigin = (value) => {
     try {
       const url = new URL(value, location.href)
@@ -231,16 +256,38 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
     }
   }
 
+  /**
+   * A package's address as the element is given it: resolved against this page, and only when it
+   * is `http` or `https`. `null` for anything else, a `javascript:` or `data:` URL or text that is
+   * not a URL. The element gets the parsed URL's `href`, never the text, so `src` holds what was
+   * checked.
+   * @param {string} value
+   */
+  const packageUrl = (value) => {
+    try {
+      const url = new URL(value, location.href)
+      return url.protocol === 'http:' || url.protocol === 'https:' ? url : null
+    } 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. */
+  /**
+   * Whether this player was told it may fetch from `origin`. Always true without a list.
+   * @param {string} origin
+   */
   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, jsDelivr's included when the pack comes
    * from there; the CSP that `h5p-embed` wrote says the same, this only says it in words.
+   * @param {string} value
+   * @returns {{ value?: string, error?: string }}
    */
   const librarySources = (value) => {
+    /** @type {string[]} */
     const sources = []
     if (value === 'none') return { value: '' }
     for (const token of value.split(/\s+/).filter(Boolean)) {
@@ -266,7 +313,8 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
    * that one away, `&refresh-libraries=off` plays a package's own libraries even where the pack
    * has newer ones, `&activity-id=` names the statements' object and `&custom-css=` restyles the
    * content to the embedding site's taste. `&lang=` is the embedding page's language, which this
-   * page cannot read across origins: H5P's own buttons and dialogs follow it. Not `custom-js`,
+   * page cannot read across origins: H5P's own buttons and dialogs follow it for a package that
+   * does not name its own language, and follow the content's where it does. 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.
    */
@@ -286,6 +334,10 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
     if (lang && /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/.test(lang)) player.setAttribute('lang', lang)
   }
 
+  /**
+   * @param {string} value
+   * @param {string | undefined} libraries
+   */
   const start = (value, libraries) => {
     if (libraries) player.setAttribute('libraries', libraries)
     if (params.get('preload') === 'auto') player.setAttribute('preload', 'auto')
@@ -319,11 +371,12 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
     refuse('No package given. Add ?src=<url of a .h5p file> to the address.', 'no-src')
     return
   }
-  const origin = urlOrigin(src)
-  if (!origin) {
-    refuse('The package address is not a URL.')
+  const address = packageUrl(src)
+  if (!address) {
+    refuse('The package address is not an http or https URL.')
     return
   }
+  const { origin } = address
   if (!permitted(origin)) {
     refuse(`This player does not play packages from ${origin}.`)
     return
@@ -339,14 +392,14 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
   // A host on the list was vouched for when the site was set up, and in another site's frame the
   // storage is that site's own: those play as they are.
   if (origin === location.origin || allowed || !sharesOriginStorage()) {
-    start(src, sources.value)
+    start(address.href, sources.value)
     return
   }
 
   // Anything else from another origin would share this origin's storage. It plays untrusted, as
   // data with the library pack's code and none of its own, and waits for a click that names the
   // host only when it cannot play without its own, or there is no pack to play it with.
-  const host = new URL(src, location.href).host || origin
+  const { host } = address
   askToTrust = () => {
     loader.hidden = true
     const button = document.createElement('button')
@@ -357,7 +410,7 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
       loader.hidden = false
       player.untrusted = false
       player.removeAttribute('src')
-      start(src, sources.value)
+      start(address.href, sources.value)
     })
     say(
       `This package from ${host} plays only with its own scripts. They would run on this site and ` +
@@ -375,5 +428,5 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null,
     return
   }
   player.untrusted = true
-  start(src, sitesSources)
+  start(address.href, sitesSources)
 }

package/types/lib/build.d.mts

@@ -0,0 +1,78 @@
+/**
+ * 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's parts from `@missing-elements/h5p-libraries` as
+ * `libraries/` — so the versions are the ones this package was published with, and nothing is
+ * fetched.
+ */
+export declare class EmbedError extends Error {
+}
+export type BuiltSite = {
+    /**
+     * the folder, as an absolute path
+     */
+    out: string;
+    /**
+     * the player's version, as its `dist/VERSION` says
+     */
+    version: string;
+    /**
+     * the policy the headers carry
+     */
+    csp: string;
+    /**
+     * whether the site carries the library pack's parts
+     */
+    libraries: boolean;
+    /**
+     * the origins packages may come from; `null` for any
+     */
+    packages: string[] | null;
+    /**
+     * the origins that may frame the page; `null` for any
+     */
+    ancestors: string[] | null;
+    /**
+     * the `libraries` value for addresses that name none
+     */
+    defaultLibraries: string | null;
+    /**
+     * the folder's size in bytes
+     */
+    size: number;
+};
+/**
+ * What `buildSite` wrote, for a summary.
+ * @typedef {object} BuiltSite
+ * @property {string} out the folder, as an absolute path
+ * @property {string} version the player's version, as its `dist/VERSION` says
+ * @property {string} csp the policy the headers carry
+ * @property {boolean} libraries whether the site carries the library pack's parts
+ * @property {string[] | null} packages the origins packages may come from; `null` for any
+ * @property {string[] | null} ancestors the origins that may frame the page; `null` for any
+ * @property {string | null} defaultLibraries the `libraries` value for addresses that name none
+ * @property {number} size the folder's size in bytes
+ */
+/**
+ * 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's parts, 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 {string | null} [options.defaultLibraries] the `libraries` value for addresses that name none
+ * @param {boolean} [options.force]
+ * @returns {Promise<BuiltSite>}
+ */
+export declare function buildSite({ out, libraries, packages, ancestors, defaultLibraries, force }: {
+    out: string;
+    libraries?: boolean;
+    packages?: string[] | string | null;
+    ancestors?: string[] | string | null;
+    defaultLibraries?: string | null;
+    force?: boolean;
+}): Promise<BuiltSite>;

package/types/site/embed.d.ts

@@ -0,0 +1,50 @@
+/*! @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|<url> …|none][&refresh-libraries=off][&preload=auto]
+ *    [&xapi=<parent origin>][&frame][&copyright][&export][&icon][&reporting][&fullscreen=off]
+ *    [&activity-id=<IRI>][&custom-css=<stylesheet url>][&lang=<language tag>]
+ *
+ * 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. Once the content is up the page posts one `report` upward, and a
+ * load that fails posts its `error` (see `report` below): what an embedding page that checks a
+ * package shows under its preview.
+ */
+import type { H5PPlayerElement } from '@missing-elements/h5p-offline-player';
+/**
+ * @param {object} [options]
+ * @param {string | null} [options.packBase] the folder of this site's copy of the library pack's
+ *   parts (`parts/` of `@missing-elements/h5p-libraries`), which `libraries=pack` plays from
+ * @param {H5PPlayerElement['pack']} [options.pack] the same, as the `pack` export a bundler
+ *   resolves; it wins over `packBase`. Without either, `pack` is the element's copy on jsDelivr
+ * @param {string | null} [options.librariesPack] the URL of a whole `libraries.h5p` on this site,
+ *   for a page written before the pack was split: played as any bundle, with no refresh
+ * @param {string[] | null} [options.packages] the origins packages and library bundles may come
+ *   from, besides this page's own; `null` plays any, one from another origin `untrusted` when the
+ *   storage is this origin's
+ * @param {string | null} [options.defaultLibraries] the `libraries` value for an address that has
+ *   none — `pack` or URLs, as the parameter — so a snippet without `&libraries=` still plays
+ *   an export that carries no libraries; `&libraries=none` turns it off for one address
+ * @param {H5PPlayerElement['runtime']} [options.runtime] the `runtime` export of `@missing-elements/h5p-runtime`,
+ *   for a page that bundles the element; without it the element looks for `frame-assets/` beside itself
+ * @param {boolean} [options.askInOwnFrame] whether a package from another origin plays `untrusted`,
+ *   with a click to play it with its own code when it needs that, when this page is framed by a
+ *   page of its own origin, whose storage it shares. A site whose own preview frames the page for
+ *   a package the visitor just chose passes `false`
+ */
+export declare function startEmbed({ packBase, pack, librariesPack, packages, defaultLibraries, runtime, askInOwnFrame }?: {
+    packBase?: string | null;
+    pack?: H5PPlayerElement['pack'];
+    librariesPack?: string | null;
+    packages?: string[] | null;
+    defaultLibraries?: string | null;
+    runtime?: H5PPlayerElement['runtime'];
+    askInOwnFrame?: boolean;
+}): void;