h5p-build-page.md

The H5P build page

/h5p/build/ is for an AI chat that wrote a source with the h5p-author skill but cannot build it. ChatGPT's sandbox reaches npm only through OpenAI's own mirror, which was reported refusing every install from July 2026, so npx @missing-elements/h5p-author does not run there, and the skill hands over the source and this page's address instead. The page builds with @missing-elements/h5p-author/browser, the same build as the command's, and lists every problem at once by its path, ready to copy back into the chat with the type files that chat lacked. Its libraries are @missing-elements/h5p-libraries/install's pack, one part per library, so a build fetches only the parts its package needs and carries the editor libraries an H5P site's upload check asks for. The package then plays in the player on the page, and downloads from it. Why it exists, and what was measured to build it this way: design/author.md of h5p-offline-player, under Where npx cannot install, a page builds.

The source is not uploaded: the package is built in the browser. A link can carry the source in its fragment, which no server sees: /h5p/build/#source=<base64url>, the bytes being the source's JSON as UTF-8, or that JSON compressed with raw deflate (Node's zlib.deflateRawSync, Python's zlib.compressobj(wbits=-15)) to keep the link short. A linked source is built at once, unless it names files of its own, which only the person can choose. A page opened by such a link keeps the fragment in step with the source as the person changes it, so the address can be copied to send the changed source on (below). A source that names a picture by web address gets it only where that host allows CORS.

File	What it holds
src/h5p/build/index.njk	The page's markup, in the site's layout, and its Content-Security-Policy: GitHub Pages cannot send a Content-Security-Policy header for a site, so a <meta> tag is the only policy it gets
src/h5p/build/build-page.ts	The page's wiring: the build, the player, the download, a link's source and the address that follows it
src/h5p/build/build-source.ts	What it does with a source with no DOM: the link's fragment, read and written, the files a source names, the content types it is written in, the text for the chat
src/h5p/build/editor.ts	The source's editor, CodeMirror 6, mounted in a shadow root and loaded apart from the page: see The source editor
src/h5p/build/json-scan.ts	What it reads of JSON text with no DOM: where a text stops being JSON and what is wrong there, where a problem's path points, and the source laid out
src/assets/site.css	Its styles, under H5P build page, in the site's own colours: the steps as a timeline, a marker for each on a rail to the next, which shows a check or a warning from what its step says of itself (#source-state, the files' data-chosen, #status), with no script of its own
vite.config.ts	The page's script, /h5p/build/build-page.js, with the player, its runtime, the pack and their licence files in /h5p/assets/, and the type files in /h5p/build/types/
e2e/, playwright.config.ts	The browser tests: a pasted source, one from a link and one with a file of its own build, play and download; the source's editor marks a mistake and the problems the build finds, lays a whole paste out, and a link follows the source as it changes; json-scan.spec.ts tests the reading of JSON with no browser; a source's problems are listed, and copied for the chat with the type files; /h5p/bundles/ serves every bundle and part, and its tool and a bundle build a quiz in an empty folder; /h5p/skill/ serves the skill's files as the package carries them, and writes out every address

The player's Service Worker is in /h5p/assets/ too, so its scope is /h5p/assets/h5p/: no other page of the site is under it. The address names who runs the page, as H5P Group's trademark policy asks of a name with "H5P" in it, and the page uses the word descriptively.

The page and the bundles were embed-my.github.io's /build and /bundles/ until 2026-11-10. Its /build is now a page that sends a visit here with its fragment, so the links chats wrote before still build (embed-my/embed-my.github.io#18).

The source editor

A person who gets a source from a chat is a teacher, not a developer, and a missing comma or quote is invisible in a textarea until Build says the source cannot be read. So the source is edited in an editor. editor.ts is CodeMirror 6, and build-page.ts loads it apart from the page (import('./editor'), a chunk of its own in /h5p/assets/). Where it cannot load, the textarea stays as the source and the page works. The textarea stays under the editor, hidden, holding the same text, so the rest of the page reads the source as it always did.

• JSON in colours, with line numbers, matching brackets and undo. The colours are the site's token colours, custom properties that reach into the editor, so light and dark need no code.
• A mistake in the JSON is marked as it is typed, and said under the source with its line and column, in words for someone who does not write JSON ("A comma is missing here"), with a button that goes there. JSON.parse still decides whether text is JSON. json-scan.ts says where, because JSON.parse says it differently in each browser and Safari does not say at all. parseSource uses it too, so the copy for the chat carries the line and the column.
• The problems the build finds are marked where they are, and the name of a problem in the list is a button that goes there. A problem's path, params.chapters[0].metadata.title, is looked up in the text by locate: a name and its value, and for what the source is missing, the object it is missing from. The marks are of the text as it was built, so a change to the text clears them.
• A source arrives laid out, so the page has no Format button. One opened from a link or a file, or pasted over all of the text or into an empty editor, is laid out by formatSource, two spaces and a field to a line, and taken out of the code fence a chat may have put it in. A paste into the text goes in as it is, and so does text that is not JSON: the line under the source says where it stops being JSON. Where the editor cannot load, the textarea lays a whole paste out too.
• A link that carried the source follows it. A page opened with #source= replaces its address when the source changes to another source: history.replaceState, so the history gets no entry and no hashchange fires, and the page does not read the address back. The address carries compactSource of the text, the JSON on one line, compressed with raw deflate where there is a CompressionStream and that is shorter (fragmentFromSource), which is what sourceFromFragment reads. So a change of layout writes nothing, and neither does text that is not JSON or not an object: the address keeps the last source it carried, and a link never carries a broken one. An emptied editor leaves #source= with nothing after it, so the page keeps following, and a link that could not be read gives way to the first source written. A page opened with no source in its address writes none. The write waits for the typing to pause, since Safari throws on more than a hundred replaceState calls in thirty seconds, and one it refuses is made again at the next change.

The editor has to fit the page's policy, which has no style-src 'unsafe-inline': an editor that adds a <style> to the page is refused. In a shadow root CodeMirror adopts its styles as a constructed stylesheet instead, which the policy does not govern. Chrome's own editing also gives text typed over a selection of coloured text a style attribute, which the policy refuses and reports; contenteditable="plaintext-only" does not stop it. So the editor takes that typing itself (typeOverSelection), through its input handlers, and a bracket or a quote typed over a selection still wraps it. Tab is not the editor's: it leaves it, so the keyboard is never trapped. The browser tests that watch the page fail on any policy report.

The type files

A chat in a browser, such as Gemini in Chrome, has the skill's text and none of its files, and can run nothing. It guesses how a content type is written, and each round of problems tells it the names of one level. So Copy the problems for the chat copies more than the list: after the problems come the skill's type files of the source's own content type and of the libraries named below it, each a type's notes, an example and its fields. The source's own type is the one the build takes it to be, h5p-author's sourceType (since 0.8.0): its type as written or as it is spoken of, "interactive-book", or with none the one under contentType or library, as a chat with no skill text writes it. Below it, a library counts by its machine name, under any key: a slide's element { "type": "text" } is no H5P.Text.

The build page found 2 problems in the source. Fix them all and write the whole source again:
- params.chapters[0]: is the params of sub-content, without the sub-content around them: write params.chapters[0] as { "library": "H5P.Column", "params": { "content": … } }
- params.chapters[0].metadata.title: is required: the chapter's name in the table of contents

How these content types are written, from the h5p-author skill's type files:

# Interactive Book (H5P.InteractiveBook)
…

vite.config.ts writes them to /h5p/build/types/<Type>.md from the pinned @missing-elements/h5p-author, which carries them since 0.7.0, with index.json, the author's version and the types there is a file for. They are that release's, so they describe the fields of the build the page runs, and a Dependabot update of the package moves both. /h5p/skill/references/types/ serves the same files: see the skill page. The page fetches them when it lists a source's problems, so the copy is written within the button's press; where they cannot be fetched, the problems are copied alone.

Measured

Measured in h5p-offline-player#172 on the weakest Claude model, Haiku 5.5, in that position: with the files beside the first problems, 42 of 46 sources of 23 content types were right by its second reply, and 29 without them. And in #174, with no skill text at all, the position of a chat given only a link to the skill: with h5p-author 0.7.1 and the file of a type named as it is spoken of, 10 of 12 sources were right by the second reply and all 12 by the third; with 0.7.0 and the page's rule before, 3 and 8 by the fourth, four never.

The page copies that text byte for byte. The 14 rounds that failed in the second test were built again on this page, and each copied what the model had been given. Of the 39 sources that failed their first build in the first, 36 did; the other three carry the same type files, and their problems read better since: a Game Map (0.7.0), and two books whose chapters had a title beside them, 13 problems now 7 (0.7.1).