@missing-elements/h5p-offline-player 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

@@ -0,0 +1,273 @@
+# @missing-elements/h5p-offline-player
+
+> **Not production ready.** This is an early release under active development. The API, the
+> worker protocol and the cache layout can still change between versions, and the browser
+> coverage is Chromium first. Try it, report what breaks, but do not put it in front of learners
+> yet.
+
+A browser-only H5P player, as one web component. It plays an arbitrary `.h5p` archive from a URL
+or from disk — no server-side extraction, no backend, nothing to unpack ahead of time.
+
+```html
+<script type="module" src="h5p-player.js"></script>
+<h5p-player src="https://host.example/course.h5p"></h5p-player>
+```
+
+Setting `src` loads, the way it does on `<video>`.
+
+## Getting started
+
+The player is three things: the element (`h5p-player.js`, an ES module), a Service Worker script
+(`h5p-sw.js`) and a folder of H5P runtime files (`frame-assets/`). The worker is the one file that
+has to be served from **your own origin**, because browsers refuse to register a worker from
+anywhere else. The other two can come from your bundle or from a CDN.
+
+> The package is being published to npm. Until it lands, build it from source: `git clone`,
+> `npm install`, `npm run build`, and serve `dist/` where the snippets below say the package's
+> files go.
+
+**A · With a bundler** (Vite, webpack 5, Rollup):
+
+```bash
+npm i @missing-elements/h5p-offline-player
+```
+
+```js
+import '@missing-elements/h5p-offline-player'
+```
+
+```html
+<h5p-player src="https://host.example/course.h5p" auto-resize></h5p-player>
+```
+
+That is all. The element finds its worker and runtime files with
+`new URL('./h5p-sw.js', import.meta.url)`, which these bundlers copy into the build and rewrite.
+A bundler that does not follow that pattern, esbuild among them, leaves the files behind: then
+serve the package's `dist/` folder from a static path and set `sw` and `assets-base` to it.
+
+**B · No build step:**
+
+```html
+<script type="module"
+  src="https://cdn.jsdelivr.net/npm/@missing-elements/h5p-offline-player/dist/h5p-player.js"></script>
+<h5p-player src="https://host.example/course.h5p" sw="/h5p-sw.js" auto-resize></h5p-player>
+```
+
+Copy `dist/h5p-sw.js` from the same CDN path onto your site and point `sw` at it. The frame assets
+keep loading from the CDN. At the root its scope is `/h5p/`, not `/`, so an existing site worker
+is left alone.
+
+**C · An iframe, nothing on your site:** frame the hosted player page,
+`/embed?src=<package url>`. It sizes itself through H5P's own resizer protocol and relays xAPI
+statements to your page on request. See Setup C in the setup guide.
+
+Requirements: the page is on `https://` or `localhost`, and the package's host sends CORS
+headers. `Range` support on the host is optional; without it the archive is downloaded once and
+played from the browser's cache.
+
+```js
+const player = document.querySelector('h5p-player')
+player.addEventListener('xapi', (event) => send(event.detail.statement))
+player.addEventListener('error', (event) => {
+  if (event.detail.code === 'no-cors') offerFilePicker()
+})
+input.addEventListener('change', () => { player.file = input.files[0] })
+```
+
+The full guide, with single-worker hosts and troubleshooting, is
+[h5p-player-setup.md](h5p-player-setup.md).
+
+## How it works
+
+An `.h5p` file is a zip. Normally a server unpacks it and serves the files; here a Service Worker
+reads the archive in place and answers the H5P runtime's requests out of it:
+
+- the archive's **central directory** is read over HTTP `Range` requests, so a 300 MB package
+  costs a few kilobytes before it starts;
+- **large spans are pulled by several connections at once** and reassembled in order, because a
+  single connection is often capped well below the link;
+- **small entries and scripts** are inflated once into a Cache API store;
+- **large stored media** is sliced straight out of the archive — never extracted, never stored;
+- **large deflated media** is inflated into 8 MB chunks by a page-side worker, and served
+  progressively as a shorter `206` so a cold video starts before extraction finishes;
+- the **frame document** the runtime lives in is generated by the worker, with a per-response CSP.
+
+Nothing larger than one chunk is ever held in memory. A host that does not honour `Range` is
+handled by downloading the archive into the chunk store — indexed from its local headers as it
+arrives, so a package laid out libraries-first boots while its media is still coming down. A host
+with no CORS headers cannot be read by any browser, and the element says so with `error: no-cors`
+so the page can offer a file picker instead.
+
+## API
+
+```html
+<h5p-player
+  src="…"            package URL — setting it loads; setting it again aborts and reloads
+  sw="…"             worker URL (default: h5p-sw.js next to the element, same-origin)
+  assets-base="…"    directory of the frame assets (default: next to the element)
+  libraries="…"      where to get libraries a package does not carry (default: nowhere)
+  allow-origins="…"  extra origins the frame's CSP should permit, space separated
+  auto-resize        follow the content's own height
+  preload="auto"     pull large deflated media before the content asks (default: none)
+></h5p-player>
+```
+
+### Video that cannot stream
+
+Most media starts playing while the rest arrives. Two properties of a package stop that, and
+some exports have both:
+
+- the media is **deflated** in the zip rather than stored, so there is no byte a `Range` request
+  can reach without the whole stream up to it — and packagers routinely deflate an mp4 for a
+  0.9% saving;
+- the mp4 is **not faststart**, so its `moov` index is the last few kilobytes of the file, and no
+  frame decodes until the final byte lands.
+
+Together they mean a 220 MB video must transfer completely before it shows anything. Nothing on
+the player's side shortens that: the bytes are genuinely required. What it can do is start
+earlier.
+
+```html
+<h5p-player src="course.h5p" preload="auto"></h5p-player>
+```
+
+After the content is up, the player pulls large deflated entries in archive order, one at a time,
+so the wait happens while the learner is still on the first slide instead of when they press
+play. It waits for the content to appear first — those same bytes would otherwise compete with
+the archive reads that boot the runtime — and it never runs two at once, which would only halve
+the rate of whichever video is needed first.
+
+It is off by default: it spends a learner's bandwidth on media they may never reach, and that is
+the host's call. Progress arrives as `progress` events with `phase: 'extract'`.
+
+The real fix belongs to whoever builds the package, and the repository ships it as a script:
+
+```bash
+npm run normalize -- course.h5p                    # writes course.normalized.h5p beside it
+npm run normalize -- https://…/course.h5p --dry-run  # inspect only
+```
+
+It rewrites the container and leaves the content alone: media is stored rather than deflated, an
+mp4 whose index sits at the end is remuxed so the index comes first, entries are ordered so the
+libraries arrive before the media, and text an exporter left stored is deflated. The package
+grows by about 1% and any H5P host still accepts it. For the 220 MB example above, the video
+starts after about a megabyte instead of after the last byte, and seeking works at once.
+
+### What the frame is allowed to reach
+
+The frame runs untrusted content under a generated CSP. Media, images and iframes are open, so
+embedded video works; scripts are same-origin plus a short list of what content types genuinely
+load at runtime — MathJax for H5P.MathDisplay, Google's WebFont loader, and the YouTube, Vimeo
+and Panopto player APIs that H5P.Video puts in the document before it embeds anything.
+
+For a host the list cannot know about — a tenant's own Panopto or Echo360 server, an in-house
+CDN — `allow-origins` adds it:
+
+```html
+<h5p-player src="…" allow-origins="https://tenant.panopto.com https://cdn.corp.example"></h5p-player>
+```
+
+It only ever adds hosts. Anything that is not plainly a host is dropped, so a stray value cannot
+append directives of its own. A blocked resource names its directive and origin in the console.
+
+The policy allows `'unsafe-eval'`. Packages that bundle EmbeddedJS — board games, older question
+sets — compile their templates with `eval` and render nothing without it. It gives an attacker no
+reach the archive's own scripts lack: those are served from the frame's origin and already run
+under `'self'`, so anyone who can put a file in the package can already run what they like. What
+the policy is for is limiting where code and data can come *from*, and this does not widen that.
+
+### Packages without libraries
+
+Exports from h5p.com and h5p.org routinely contain `content/` and nothing else: the site they
+came from already has the libraries, so bundling them would be waste. Anywhere else such a
+package cannot run, and the runtime's only symptom is a 404 for `<MainLibrary>/library.json`.
+
+The player refuses these up front and names what is absent. `libraries` tells it where to look
+instead:
+
+```html
+<!-- the official H5P content-type server, keyed on the package's mainLibrary -->
+<h5p-player src="stripped.h5p" libraries="hub"></h5p-player>
+
+<!-- or any .h5p that carries the library folders -->
+<h5p-player src="stripped.h5p" libraries="/h5p/libraries-bundle.h5p"></h5p-player>
+```
+
+Entries then resolve against the package first and the bundle second, and the two `h5p.json`
+manifests are merged — a stripped export also cuts `preloadedDependencies` down to the main
+library, so without the merge an Interactive Video would load but its interactions would not. The
+bundle is downloaded once, cached, and shared by every package that uses it.
+
+It is off by default. `libraries="hub"` is a request to a third party on every cold load, which is
+the host's decision to make, not the element's.
+
+Properties: `src`, `file` (a `File` from a picker — setting it loads), `pkgId`, `state`
+(`idle | probing | downloading | indexing | ready | error`), `scope` (read-only).
+
+| Event | When |
+|---|---|
+| `ready` | The runtime is up and the content is visible |
+| `xapi` | Any xAPI statement from the content — the only channel for results; nothing is stored |
+| `finished` | The content reported completion, with its score |
+| `progress` | Download or extraction progress, `fraction` 0–1 (or `null` when the total is unknown) |
+| `resize` | The content's height changed |
+| `statechange` | `state` changed |
+| `error` | `code`: `no-cors`, `no-worker`, `network`, `quota`, `bad-archive`, `runtime` |
+
+```js
+const player = document.querySelector('h5p-player')
+player.addEventListener('xapi', (e) => console.log(e.detail.statement))
+player.addEventListener('error', (e) => {
+  if (e.detail.code === 'no-cors') showDownloadHint()
+})
+input.onchange = () => (player.file = input.files[0])
+```
+
+The element renders the content and nothing else — no URL field, no file picker, no progress bar,
+no "open in another browser" banner. Those belong to the host page, built out of these events.
+`index.html` in this repo is a working example of one.
+
+## Requirements
+
+- The page is served over `https://` or `localhost`. Service Workers do not run on `http://` or
+  `file://`.
+- `h5p-sw.js` is served from the site's own origin — browsers reject cross-origin Service Worker
+  registration. With a bundler this is automatic. Frame assets may come from a CDN.
+- Package URLs send CORS headers. `Range` support is optional but avoids a full download first.
+
+Integration details, including bundler-specific setup and single-worker hosts, are in
+[h5p-player-setup.md](h5p-player-setup.md). The design is in
+[h5p-offline-player-architecture.md](h5p-offline-player-architecture.md).
+
+## Development
+
+```bash
+npm install
+npx playwright install chromium   # once, for the browser tests
+
+npm run dev     # the demo player page on http://localhost:5173
+npm test        # unit tests plus the browser suite
+npm run build
+npm run normalize -- course.h5p   # rewrite a package so it streams (see above)
+npm run build:demo                # the hosted demo, as Vercel builds it, into dist-demo/
+npm run preview:demo              # serve it locally with the production headers
+npm run demo:content              # rebuild the demo's content packages from their sources
+```
+
+`npm run dev` serves the player page with real content — a quiz, an interactive video, an
+accordion and dialog cards, built from H5P hub libraries around text written for this player —
+plus, in dev only, generated test archives under `/fixtures/` covering each path the player
+takes: a host that honours `Range` and one that does not, 20 MB of deflated and of stored media,
+hostile entry names, a file that is not an H5P package. `/demo/` is the two-line integration,
+with the other ways to embed it — xAPI, a file from disk, an iframe, two players on one page —
+linked from there.
+
+The demo site deploys to Vercel from `vercel.json`: the pages, the element, its worker and the
+frame assets as static files, plus one function that plays a host without `Range` support.
+
+Working on the code? Start with [AGENTS.md](AGENTS.md).
+
+## Licence
+
+MIT. Bundles [h5p-standalone](https://github.com/tunapanda/h5p-standalone) (MIT) as the runtime
+and [zip.js](https://github.com/gildas-lormeau/zip.js) (BSD-3-Clause) as the archive reader.

package/dist/VERSION

@@ -0,0 +1 @@
+0.1.0

package/dist/frame-assets/MANIFEST.json

@@ -0,0 +1,4 @@
+{
+  "h5pStandalone": "3.8.2",
+  "player": "0.1.0"
+}

package/dist/frame-assets/fonts/inter/LICENSE.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/frame-assets/fonts/open-sans/OFL.txt

@@ -0,0 +1,88 @@
+Copyright 2020 The Open Sans Project Authors (https://github.com/googlefonts/opensans)
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to
+provide a free and open framework in which fonts may be shared and
+improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software
+components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to,
+deleting, or substituting -- in part or in whole -- any of the
+components of the Original Version, by changing formats or by porting
+the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed,
+modify, redistribute, and sell modified and unmodified copies of the
+Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the
+corresponding Copyright Holder. This restriction only applies to the
+primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created using
+the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.