Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,8 @@ folders; in `design/`, `src/…` and `scripts/…` mean the player's unless a fi
| `packages/libraries/` | the library pack, one archive per library | [libraries](design/libraries.md) |
| `packages/normalize/` | rewrites a package so it streams | [normalize](design/normalize.md) |
| `packages/verify/` | plays a package headless and reports | [verify](design/verify.md) |
| `packages/author/`, `skills/h5p-author/` | a playable package of any content type from a short source | [author](design/author.md) |
| `packages/mcp/` | the local MCP server: builds, checks and previews in an app with no shell | [mcp](design/mcp.md) |
| `packages/author/`, `skills/h5p-author/` | a playable package of any content type from a short source, and a package back to one | [author](design/author.md) |
| `packages/mcp/` | the local MCP server: builds, reads, checks and previews in an app with no shell | [mcp](design/mcp.md) |
| `packages/cmi5/` | the element as a cmi5 assignable unit | [cmi5](design/cmi5.md) |
| `packages/embed/`, `skills/h5p-to-scorm/` | the embed site for a player domain, and a package as a SCORM zip | [embed](design/embed.md), [scorm](design/scorm.md) |
| `packages/vscode/` | H5P Preview, the VS Code extension | [vscode](design/vscode.md) |
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,8 @@ npx @missing-elements/h5p-verify@latest course.h5p
| [`@missing-elements/h5p-embed`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/embed#readme) | The player page as a static site, and a package as a SCORM zip |
| [`@missing-elements/h5p-verify`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/verify#readme) | Plays a package headless and reports whether it works, or opens it in your browser |
| [`@missing-elements/h5p-normalize`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/normalize#readme) | Rewrites a package so its video streams |
| [`@missing-elements/h5p-author`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/author#readme) | Builds a package of any content type from a short JSON source |
| [`@missing-elements/h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) | A local MCP server: an app such as Claude Desktop builds a package onto your disk, checks it and opens it in your browser |
| [`@missing-elements/h5p-author`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/author#readme) | Builds a package of any content type from a short JSON source, and reads one back into its source |
| [`@missing-elements/h5p-mcp`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/mcp#readme) | A local MCP server: an app such as Claude Desktop builds a package onto your disk, checks it and opens it in your browser, or reads one to change it |
| [`@missing-elements/h5p-cmi5`](https://github.com/missing-elements/h5p-toolkit/tree/main/packages/cmi5#readme) | Makes a page holding the element a cmi5 assignable unit |
| [H5P Preview](https://marketplace.visualstudio.com/items?itemName=MissingElements.h5p-preview) | Plays `.h5p` files in VS Code, and from [Open VSX](https://open-vsx.org/extension/MissingElements/h5p-preview) in Cursor and VSCodium |

Expand Down
42 changes: 39 additions & 3 deletions design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,41 @@ text to the content check's rules, and `apps/skills` plays every example untrust
too, as the editor's `initSubContent` gives one, since Summary names a statement's statements by
it. Of the owner's 88 real packages, 61 report nothing; the others hold what their editor let an
author save, such as an empty alt text or styles pasted from Word.
- **A package reads back into a source, by the generator's own rules walked back** (#236, step 3
of #219). `readPackage` and `h5p-author read` write the source a build would take to make the
package again, its media beside it at the paths the source names them by.
- Its own fields are `h5p.json`'s; a package with no author reads as "Unknown". `params` are
`content.json` as `checkContent` returns it, less what a build fills in, worked out by
`ContentGenerator.written`: of each field, what the generator writes there with nothing
written, at the field's own level with the saved values beside it taken as written, so a
`showWhen` reads them as it reads a source. The libraries are loaded in the content's
language, so an interface text equal to its translation drops out as any default does.
- Left out besides: a part's id, and its metadata but its title; a title the build gives, its
content type's or Question Set's own (the layout's `read`); and what H5P's editor saves for an
author who never touched it, as `checkContent` takes it: an empty text or choice, a list it
started whose items are only an item's defaults (Interactive Video's text track with no file),
and a default's content nobody opened (its summary task). Markup that is only the blocks a
build wraps typing in is written as the typing (`unwrapText`, held by `wrapText`); Game Map's
neighbours go back to numbers. Positions and sizes are kept as written.
- The source is then built in memory, the package's files standing for themselves, and held to
the content as checked: a text, a number, a flag or a title that comes back otherwise is
written as stored, anything else is a note, and so is what a build of it would refuse.
- Only content for the pack's major.minor of every library it names is read; any other is
refused with both versions named, since moving it is the library's own upgrade, the runtime's
(GPL). Of the owner's 88 real packages, 58 were refused so, mostly Interactive Video 1.27 and
Course Presentation 1.25 and 1.26. Of the other 30, 26 build as read; 4 need what their notes
name: pictures missing from the package, styles pasted from Word, a question with one answer,
and H5P.Row's column widths with decimals, which its editor sets and the number rule refuses.
- What a source has no field for is said and left out: the author's comments, the change log,
the licence's extra terms, and a part's own licence or authors, a build giving every part the
source's.
- An archive is untrusted: only the media the content names are written, under the folder, each
path checked before anything is made, so that a link in the folder leading out of it stops the
read; a file named by a path that could lead out is left out of the source, which so names no
file outside its folder; one whose entry leads out of its folders is not read. Nothing is
written over, and nothing at all where a name is taken; a read that fails takes away what it
made. Every type file's example, built, read and built again, is the same content and media
but for the ids, with no note (`read.test.ts`).
- **A page builds too** (#108). The package has three entries: `.` for Node, `./core` for what
needs neither Node nor a page, and `./browser`, the core and a page's `openPack` and
`buildPackage`. They are subpaths and not the `browser` condition, which TypeScript ignores
Expand Down Expand Up @@ -416,6 +451,7 @@ text to the content check's rules, and `apps/skills` plays every example untrust
errors, a sandbox that downloads only what a browsing tool has opened, a code tool that can be
unavailable for hours.

Not built: editing an existing package, which a tool beside it does with `checkContent` as its
check; layout for Drag and Drop and Crossword; and any judgement of whether content is right, which
stays the person's, in the verifier's preview.
Not built: changing a package in place, which a tool beside it does with `checkContent` as its
check (a package is changed by reading it into a source and building that); reading content made
for another version of a library than the pack's; layout for Drag and Drop and Crossword; and any
judgement of whether content is right, which stays the person's, in the verifier's preview.
5 changes: 3 additions & 2 deletions design/layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ packages/verify/ a package played headless (lib/verify.mjs) and in a brows
(lib/preview.mjs); lib/serve.mjs what both share, which the extension bundles
packages/author/ a playable .h5p from a short source: lib/build.mjs both builds, node.mjs
Node's, generator.mjs content from semantics, check.mjs, outline.mjs,
types.mjs the editor widgets' rules; scripts/ the skill's sync and copy
packages/mcp/ the local MCP server: bin/h5p-mcp.mjs the command, lib/server.mjs its three
types.mjs the editor widgets' rules, read.mjs a package back to a source;
scripts/ the skill's sync and copy
packages/mcp/ the local MCP server: bin/h5p-mcp.mjs the command, lib/server.mjs its four
tools, lib/folders.mjs the folders it may use
packages/cmi5/ the element as a cmi5 AU: src/index.ts startCmi5, src/client.ts the protocol
packages/embed/ site/ the embed page and the SCORM page; lib/build.mjs the site,
Expand Down
40 changes: 25 additions & 15 deletions design/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,24 @@

`packages/mcp` is `@missing-elements/h5p-mcp`, shown as **H5P Author MCP by Missing Elements**: a
local MCP server over standard input and output that builds a package onto the person's disk,
checks it, and opens it in their browser. It is for apps with no shell, Claude Desktop first; in an
app with a shell, the skill and `npx` build already. A remote server, for ChatGPT or Claude on the
web, is #210 and not this.
checks it, and opens it in their browser, or reads one back to change it. It is for apps with no
shell, Claude Desktop first; in an app with a shell, the skill and `npx` build already. A remote
server, for ChatGPT or Claude on the web, is #210 and not this.

- **It holds no rules of its own.** The build, its checks, the outline and the confinement to
folders (`buildPackage`, `within`, `publicFetch`, `inside`) are h5p-author's; the check, the
preview and opening the browser (`verifyPackage`, `summarize`, `previewPackage`, `openBrowser`)
are h5p-verify's. A rule a tool needs goes into those packages first, exported, so the author
package and the verifier are published before a server that uses something new of theirs.
- **Three tools, and the skill's flow as the instructions.** `h5p_types` lists the pack's content
- **It holds no rules of its own.** The build, the read, their checks, the outline and the
confinement to folders (`buildPackage`, `readPackage`, `within`, `publicFetch`, `inside`) are
h5p-author's; the check, the preview and opening the browser (`verifyPackage`, `summarize`,
`previewPackage`, `openBrowser`) are h5p-verify's. A rule a tool needs goes into those packages
first, exported, so the author package and the verifier are published before a server that uses
something new of theirs.
- **Four tools, and the skill's flow as the instructions.** `h5p_types` lists the pack's content
types, those with a type file marked, and the skill's brief; given a type, read as a build reads
one (`sourceType`, so "true false" works), it answers with the type's file, or with `schemaOf` for
a type with none. `h5p_build` builds a source and `h5p_preview` opens a package. The instructions
are the flow in a few lines: the type is the one question, its answer is read before the source is
written, then the build, where the file is and what the check found, and the preview offered.
Not `SKILL.md`, whose build routes do not apply here. An app sends the descriptions and the
a type with none. `h5p_build` builds a source, `h5p_preview` opens a package, and `h5p_read`
reads one back into its source. The instructions are the flow in a few lines: the type is the one
question, its answer is read before the source is written, then the build, where the file is and
what the check found, and the preview offered; a package the person has is read, its source
changed, and built. Not `SKILL.md`, whose build routes do not apply here. An app sends the descriptions and the
instructions with every message, so they stay under about 1,500 tokens; `server.test.ts` holds
them under 6,000 characters.
- **`h5p_build` shows a source's own fields; the build checks them.** Its `source` carries the
Expand Down Expand Up @@ -49,6 +51,15 @@ web, is #210 and not this.
in a temporary folder, with its screenshot as an image. Where neither Chrome, Edge nor
Playwright's Chromium is found, the answer says "Not verified" and why. A source with problems
is refused, every problem by its path, and nothing is written.
- **A read writes beside the package, and names its files where it wrote them** (#236).
`h5p_read` takes a package in the folders, a name alone being the first folder's, and writes its
source and media into a new folder beside it, named after it and numbered where the name is
taken, as a package is. It answers with the source, each file named by its full path in that
folder, so `h5p_build` reads them wherever its package goes, and looks for one the package lacks
there and nowhere else. Asked to add two harder questions to the
demo's quiz, Haiku read it and built at the first build in 6 of 6 runs. With the package
described as a path in the server's folders, it first guessed one from its working folder in 3
of 3; described "by its file name alone", in none of 3.
- **The SDK is v2, and the package ships its source.** `@modelcontextprotocol/server` brings only
its core and zod, none of the HTTP frameworks v1 installed, so `bin/` and `lib/` are published as
written, with no bundle. `McpServer` on `StdioServerTransport` serves the 2025 protocol, which
Expand All @@ -62,5 +73,4 @@ web, is #210 and not this.
one refused. Each test builds what it needs, so each runs alone. The test script first copies
the skill's type files into the author package, as the author's `prepack` does.

Not built yet: reading a package back to a source (step 3 of #219), the MCP registry's
`server.json` and Claude Desktop's one-click bundle.
Not built yet: the MCP registry's `server.json` and Claude Desktop's one-click bundle.
44 changes: 39 additions & 5 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@ type, and only the fields that differ from its defaults. The rest comes from the
`semantics.json` and their translations for the content's language; the libraries come from
[@missing-elements/h5p-libraries](https://www.npmjs.com/package/@missing-elements/h5p-libraries),
the pack this release pins, each checked against the pack's SHA-256 index. No H5P server, no
editor, no network but for media named by web address. Needs Node 22 or later; write `@latest`,
since without it npm on an older Node quietly installs an older release.
editor, no network but for media named by web address. `read` turns a package back into its
source, to change it and build it again. Needs Node 22 or later; write `@latest`, since without it
npm on an older Node quietly installs an older release.

```bash
npx @missing-elements/h5p-author@latest build rivers.json rivers.h5p
Expand Down Expand Up @@ -147,6 +148,33 @@ packs them as the zips chat apps install, and lists the build tool and each bund
skill's route 3, from two files, fetches at
[missing-elements.github.io/h5p/skill/](https://missing-elements.github.io/h5p/skill/).

## A package back to its source

```bash
npx @missing-elements/h5p-author@latest read rivers.h5p rivers
```

```
Read /work/rivers.h5p: H5P.Blanks. Wrote its source to /work/rivers/rivers.source.json.
Change it, then build it again: h5p-author build rivers/rivers.source.json <output.h5p>
```

The source holds what a build takes to make the package again: the content type and the metadata
from its `h5p.json`, and of its content only what differs from the defaults, interface texts in the
content's language included. Its pictures, videos and other files go beside the source, at the
paths it names them by. Positions and sizes are kept, so a slide or a video keeps its layout. Each
part gets a new id when it is built again.

It reads content made for the pack's versions of its libraries, and refuses any other, naming both
versions. H5P moves content to a newer version as it plays it, so a package saved again on a site
that has the pack's versions reads. What a source has no field for, or no form of, is said and left
out: the author's comments, the change log, a part's own licence or authors (a build gives every
part the source's), a file's licence that H5P does not list. The source is built again in memory
before it is written, and what would not come back as it is, or what a build would refuse, such as
styles pasted from Word, is said, to fix before building. It never writes over a file. An archive
is untrusted: only the files its content names are written, only under the folder, and a file
named by a path that could lead out of it is left out of the source.

## A content type's bundle

```bash
Expand Down Expand Up @@ -212,6 +240,12 @@ const source = JSON.parse(await readFile(join(folder, 'rivers.json'), 'utf8'))
const { outline } = await buildPackage(source, join(folder, 'rivers.h5p'), { base: folder, within: [folder], fetch: publicFetch })
```

`readPackage(file, folder, { libraries, within })` reads a package back into its source, as
`h5p-author read` does, and returns `{ output, source, files, notes }`: the source's path, the
source, the media written beside it by the paths it names them by, and what was left out or would
not come back as it is, each `{ path, message }`. With `within`, the package and the folder must be
inside those folders, on their real paths.

A result's `libraries` are the folders the package
plays with, `install` those carried for an H5P site's upload check. `missingForInstall(libraries)`
is that check, over a package's `library.json` files: what a site with no library installed would
Expand Down Expand Up @@ -343,8 +377,8 @@ the package's main export has them. A tool beside a build in either imports it f

It checks structure, not pedagogy: whether the answers are right, the questions fair, or the
pictures placed well is for a person to judge, in
[h5p-verify](https://www.npmjs.com/package/@missing-elements/h5p-verify)'s `--preview`. It does not
edit an existing package itself: `checkContent` is the check for a tool that does. The licence of
each library is in the pack's `libraries.txt`.
[h5p-verify](https://www.npmjs.com/package/@missing-elements/h5p-verify)'s `--preview`. It changes an
existing package only by way of its source, read and built again; `checkContent` is the check for a
tool that changes one in place. The licence of each library is in the pack's `libraries.txt`.

MIT.
Loading
Loading