@missing-elements/h5p-embed 0.1.0 → 0.2.0

package/README.md

@@ -38,6 +38,7 @@ cookies and nothing else on it.
 |---|---|
 | `--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 |
+| `--default-libraries <sources>` | The `libraries` value for addresses that name none, so a snippet without `&libraries=` still plays an export that carries no libraries (h5p.com and h5p.org exports usually do not): `pack`, `hub`, URLs, as the parameter. Checked against `--packages` when the site is written. Default: none, and such exports are refused unless the address asks |
 | `--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 |
 
@@ -77,7 +78,7 @@ redeploy.
 | 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 |
+| `libraries=pack`, `hub`, `<url>` or `none` | Libraries for an export that has none (h5p.com and h5p.org exports usually do not); `none` turns off the site's `--default-libraries` for this address. `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 |
@@ -110,6 +111,25 @@ The checks prove where a message came from, not what it says: a package can post
 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.
 
+## Messages to the embedding page
+
+Besides the heights and the relayed statements, the frame posts two messages to its parent,
+whatever `xapi=` says. Neither carries anything the embedding page did not hand over itself.
+
+```js
+// Once, when the content is up: what the player learnt about the package.
+{ context: 'h5p-offline-player', action: 'report',
+  source,         // { type: 'range-http' | 'chunked' | 'file', size }: streamed, or downloaded whole
+  metadata,       // { title, license, licenseVersion, authors: [names], mainLibrary }, from h5p.json
+  libraryBundle,  // { url, origin, fromCache } when libraries came from a bundle, else null
+  elapsedMs }     // from setting the package to the content being up
+
+// Instead, when the load fails, or the page refuses the address (code: 'refused', or 'no-src').
+{ context: 'h5p-offline-player', action: 'error', code, message }
+```
+
+The strings in `metadata` are the package's own; show them as text.
+
 ## As a library
 
 ```js
@@ -118,8 +138,27 @@ 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.
+`@missing-elements/h5p-embed/embed.js` exports `startEmbed()`, the page's script, for a site
+that builds the page into its own pipeline. It reads the page's `<h5p-player>`, `#loader` and
+`#notice` (see `site/index.html`, and `site/embed.css` for their styles) and takes:
+
+| Option | |
+|---|---|
+| `librariesPack` | The URL of a copy of `@missing-elements/h5p-libraries`, which `libraries=pack` names |
+| `packages` | The origins packages may come from, besides the page's own; `null` for any |
+| `defaultLibraries` | The `libraries` value for addresses that name none |
+| `runtime` | The `runtime` export of `@missing-elements/h5p-runtime`, for a bundled element |
+| `askInOwnFrame` | `false` to skip the click a package from elsewhere otherwise waits for when a page of the same origin frames this one — for a site whose own preview frames it for a package the visitor just chose. Default `true` |
+
+```js
+import '@missing-elements/h5p-offline-player'
+import { runtime } from '@missing-elements/h5p-runtime'
+import librariesPack from '@missing-elements/h5p-libraries/libraries.h5p?url'
+import '@missing-elements/h5p-embed/embed.css'
+import { startEmbed } from '@missing-elements/h5p-embed/embed.js'
+
+startEmbed({ runtime, librariesPack, defaultLibraries: 'pack' })
+```
 
 ## Licences
 

package/bin/h5p-embed.mjs

@@ -16,6 +16,10 @@ Options:
                          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.
+  --default-libraries <sources>
+                         the libraries= value for addresses that name none, so a snippet without
+                         it still plays an export with no libraries: pack, hub, URLs, as the
+                         parameter. Default: none, such exports are refused unless the address asks
   --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
@@ -28,6 +32,7 @@ try {
     options: {
       packages: { type: 'string', multiple: true },
       ancestors: { type: 'string', multiple: true },
+      'default-libraries': { type: 'string' },
       'no-libraries': { type: 'boolean' },
       force: { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
@@ -61,6 +66,7 @@ try {
     libraries: !values['no-libraries'],
     packages: values.packages ?? null,
     ancestors: values.ancestors ?? null,
+    defaultLibraries: values['default-libraries'] ?? null,
     force: values.force ?? false
   })
   const below = relative(process.cwd(), site.out)
@@ -69,6 +75,7 @@ try {
   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(`Libraries for exports without them: ${site.defaultLibraries ?? 'only when the address asks'}.`)
   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:

package/lib/build.mjs

@@ -51,6 +51,47 @@ export function parseOrigin(value) {
   return url.origin
 }
 
+/**
+ * A `libraries` value for addresses that name none, checked against the site it goes into: the
+ * tokens the page understands (`pack`, `hub`, `none`, https URLs), and with a host list, nothing
+ * the page would then refuse on every load. Returns the value normalised to single spaces.
+ *
+ * @param {string | null | undefined} value
+ * @param {object} [site]
+ * @param {string[] | null} [site.packages] the site's host list, as `parseOrigins` returns it
+ * @param {boolean} [site.libraries] whether the site carries the pack
+ */
+export function parseDefaultLibraries(value, { packages = null, libraries = true } = {}) {
+  if (value == null) return null
+  const tokens = String(value).split(/\s+/).filter(Boolean)
+  if (tokens.length === 0) return null
+  if (tokens.includes('none')) {
+    if (tokens.length > 1) throw new EmbedError('--default-libraries none stands alone.')
+    return null
+  }
+  // An exact match on a parsed origin, not a substring of a URL.
+  const hubAllowed = !packages || packages.some((origin) => origin === 'https://api.h5p.org')
+  for (const token of tokens) {
+    if (token === 'hub') {
+      if (!hubAllowed) throw new EmbedError('--default-libraries names hub, but --packages does not list https://api.h5p.org.')
+    } else if (token === 'pack') {
+      if (!libraries && !hubAllowed) throw new EmbedError('--default-libraries names pack, but the site has no pack (--no-libraries) and no hub to fall back to.')
+    } else {
+      let url
+      try {
+        url = new URL(token)
+      } catch {
+        throw new EmbedError(`--default-libraries: not pack, hub, none or a URL: ${token}`)
+      }
+      if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+        throw new EmbedError(`--default-libraries: not an https URL: ${token}`)
+      }
+      if (packages && !packages.includes(url.origin)) throw new EmbedError(`--default-libraries names ${url.origin}, which --packages does not list.`)
+    }
+  }
+  return tokens.join(' ')
+}
+
 /** Origins given as a list, or as one string separated by commas or whitespace. */
 export function parseOrigins(values) {
   if (values == null) return null
@@ -169,15 +210,17 @@ async function occupied(dir) {
  * @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 {string | null} [options.defaultLibraries] the `libraries` value for addresses that name none
  * @param {boolean} [options.force]
  */
-export async function buildSite({ out, libraries = true, packages = null, ancestors = null, force = false }) {
+export async function buildSite({ out, libraries = true, packages = null, ancestors = null, defaultLibraries = 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.')
+  const fallbackLibraries = parseDefaultLibraries(defaultLibraries, { packages: allowedPackages, libraries })
   // 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.`)
@@ -205,7 +248,7 @@ export async function buildSite({ out, libraries = true, packages = null, ancest
   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`
+    `// Written by h5p-embed: what main.js hands the page.\nexport default ${JSON.stringify({ libraries: Boolean(pack), packages: allowedPackages, defaultLibraries: fallbackLibraries })}\n`
   )
 
   const csp = contentSecurityPolicy({ packages: allowedPackages, ancestors: allowedAncestors })
@@ -214,7 +257,16 @@ export async function buildSite({ out, libraries = true, packages = null, ancest
   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) }
+  return {
+    out: target,
+    version,
+    csp,
+    libraries: Boolean(pack),
+    packages: allowedPackages,
+    ancestors: allowedAncestors,
+    defaultLibraries: fallbackLibraries,
+    size: await sizeOf(target)
+  }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@missing-elements/h5p-embed",
-  "version": "0.1.0",
+  "version": "0.2.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": {
@@ -42,24 +42,23 @@
     "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:^"
+    "@missing-elements/h5p-libraries": "^0.1.0",
+    "@missing-elements/h5p-offline-player": "^0.5.1",
+    "@missing-elements/h5p-runtime": "^0.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.4",
+    "@zip.js/zip.js": "^2.23.0",
     "playwright": "^1.50.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "test": "pnpm --filter @missing-elements/h5p-offline-player build && vitest run",
+    "typecheck": "tsc -p tsconfig.json"
   }
-}
+}

package/site/embed.js

@@ -5,7 +5,7 @@
  * `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>]
+ *   ?src=<package url>[&libraries=pack|hub|<url> …|none][&preload=auto][&xapi=<parent origin>]
  *    [&frame][&copyright][&export][&icon][&reporting][&fullscreen=off]
  *    [&activity-id=<IRI>][&custom-css=<stylesheet url>]
  *
@@ -13,7 +13,9 @@
  * 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.
+ * 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 — Embed My's preview — shows.
  */
 
 /** Where `libraries=hub` fetches from: the one hub host that sends CORS headers (see the player). */
@@ -22,13 +24,23 @@ 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
+ *   on this site, which `libraries=pack` names; without one, `pack` means the hub where allowed
  * @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
+ * @param {string | null} [options.defaultLibraries] the `libraries` value for an address that has
+ *   none — `pack`, `hub`, 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`,
+ *   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 waits for a click
+ *   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 function startEmbed({ librariesPack = null, packages = null } = {}) {
+export function startEmbed({ librariesPack = null, packages = null, defaultLibraries = null, runtime = null, askInOwnFrame = true } = {}) {
   const params = new URLSearchParams(location.search)
   const player = document.querySelector('h5p-player')
+  // Before `src`: the element resolves the runtime's files when a package is set.
+  if (runtime) player.runtime = runtime
   const notice = document.querySelector('#notice')
   const loader = document.querySelector('#loader')
   const framed = window.parent !== window
@@ -53,9 +65,10 @@ export function startEmbed({ librariesPack = null, packages = null } = {}) {
     requestAnimationFrame(announce)
   }
 
-  const refuse = (text) => {
+  const refuse = (text, code = 'refused') => {
     loader.hidden = true
     say(text, 'error')
+    post({ context: 'h5p-offline-player', action: 'error', code, message: text })
   }
 
   /* ---------------------------------------------------------------- sizing, upward */
@@ -93,6 +106,42 @@ export function startEmbed({ librariesPack = null, packages = null } = {}) {
   player.addEventListener('resize', () => requestAnimationFrame(announce))
   player.addEventListener('ready', () => requestAnimationFrame(announce))
 
+  /* ---------------------------------------------------------------- the report, upward */
+
+  /**
+   * What the player learnt about the package, for the embedding page to show: whether the host
+   * streamed it or made the browser download it whole (`source.type`), how big it is, what it
+   * says it is (`metadata`), where libraries it did not carry came from (`libraryBundle`, `null`
+   * when it carried its own), and how long it took here. Posted once, when the content is up:
+   *
+   *   { context: 'h5p-offline-player', action: 'report', source, metadata, libraryBundle, elapsedMs }
+   *
+   * and to any parent, like the heights: the parent named the package, and the manifest's strings
+   * are the package's own to tell. A parent treats them as text. A load that fails before the
+   * content is up posts `{ context: 'h5p-offline-player', action: 'error', code, message }`
+   * instead, a refusal by this page included (`code: 'refused'`). The shapes are Embed My's,
+   * whose preview is built from them.
+   */
+  let startedAt = 0
+
+  player.addEventListener('ready', (event) => {
+    const { source, metadata, libraryBundle } = event.detail
+    post({
+      context: 'h5p-offline-player',
+      action: 'report',
+      source: source && { type: source.type, size: source.size },
+      metadata: metadata && {
+        title: metadata.title,
+        license: metadata.license,
+        licenseVersion: metadata.licenseVersion,
+        authors: metadata.authors?.map(({ name }) => name),
+        mainLibrary: metadata.mainLibrary
+      },
+      libraryBundle,
+      elapsedMs: Math.round(performance.now() - startedAt)
+    })
+  })
+
   /* ---------------------------------------------------------------- xAPI, relayed on request */
 
   /** An origin, or nothing: the parameter has to be exactly what `event.origin` will read. */
@@ -126,6 +175,7 @@ export function startEmbed({ librariesPack = null, packages = null } = {}) {
         href: location.href,
         text: 'Open it on its own'
       })
+      post({ context: 'h5p-offline-player', action: 'error', code, message })
       return
     }
     // Once the content is up, a runtime error inside it is the content's business: it keeps
@@ -135,6 +185,7 @@ export function startEmbed({ librariesPack = null, packages = null } = {}) {
       return
     }
     say(message || code, 'error')
+    post({ context: 'h5p-offline-player', action: 'error', code, message })
   })
 
   player.addEventListener('statechange', (event) => {
@@ -169,6 +220,7 @@ export function startEmbed({ librariesPack = null, packages = null } = {}) {
    */
   const librarySources = (value) => {
     const sources = []
+    if (value === 'none') return { value: '' }
     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
@@ -213,6 +265,7 @@ export function startEmbed({ librariesPack = null, packages = null } = {}) {
     if (libraries) player.setAttribute('libraries', libraries)
     if (params.get('preload') === 'auto') player.setAttribute('preload', 'auto')
     applyOptions()
+    startedAt = performance.now()
     player.setAttribute('src', value)
   }
 
@@ -225,6 +278,8 @@ export function startEmbed({ librariesPack = null, packages = null } = {}) {
    */
   const sharesOriginStorage = () => {
     if (!framed) return true
+    // Treated as another site's frame: the page around it chose this package, so no click.
+    if (!askInOwnFrame) return false
     try {
       return window.parent.location.origin === location.origin
     } catch {
@@ -236,7 +291,7 @@ export function startEmbed({ librariesPack = null, packages = null } = {}) {
 
   const src = params.get('src')?.trim()
   if (!src) {
-    refuse('No package given. Add ?src=<url of a .h5p file> to the address.')
+    refuse('No package given. Add ?src=<url of a .h5p file> to the address.', 'no-src')
     return
   }
   const origin = urlOrigin(src)
@@ -248,7 +303,8 @@ export function startEmbed({ librariesPack = null, packages = null } = {}) {
     refuse(`This player does not play packages from ${origin}.`)
     return
   }
-  const libraries = params.get('libraries')?.trim()
+  // The address's own value wins, `none` included; an address without one gets the page's default.
+  const libraries = params.get('libraries')?.trim() || defaultLibraries?.trim()
   const sources = libraries ? librarySources(libraries) : { value: '' }
   if (sources.error) {
     refuse(sources.error)

package/site/main.js

@@ -6,5 +6,6 @@ import { startEmbed } from './embed.js'
 
 startEmbed({
   librariesPack: config.libraries ? new URL('./libraries.h5p', import.meta.url).href : null,
-  packages: config.packages
+  packages: config.packages,
+  defaultLibraries: config.defaultLibraries
 })