Skip to content
Merged
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
30 changes: 29 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ The hard constraints that shape every file here:

## Layout

A pnpm workspace of eight parts: seven packages and the demo app. Paths elsewhere in this file are relative to the part they
A pnpm workspace of nine parts: seven packages and two apps, the demo and the skills' test project. Paths elsewhere in this file are relative to the part they
belong to — `src/…` and `scripts/…` mean the player's unless a section says otherwise.

```
Expand Down Expand Up @@ -247,6 +247,23 @@ apps/demo/ the demo app: the dev server for the whole repository,
vite.config.ts the dev server and the hosted demo: the pages plus dist/'s layout at the
site root -> dist-demo/

apps/skills/ the skills' test project, a project of the kind a skill's user runs it in:
it installs what h5p-author tells its user to install, the library pack and
zip.js, which the script resolves from it, and the verifier the skill runs
with npx; nothing in it ships. Out of the demo since 2026-10-23, by the
owner's choice
tests/author.test.ts h5p-author's helper in Node: its quiz validation, its archives, a damaged
library part refused by its SHA-256 before anything is published, a zip.js
older than 2.24 stopped with the install command, and the skill copied
outside the checkout, resolving its dependencies from the calling project
tests/author-verify.test.ts both quiz kinds and the eight-scenario example through the verifier's
published API, trusted and untrusted against the installed pack: each a
pass with no warnings
tests/author-playback.test.ts the eight-scenario example in the verifier's preview, the review the
skill hands a person, trusted and untrusted: every question's feedback,
75% failing and 83.3% passing an 80% threshold, retry to 100%, and only
the parent Question Set finishing; Chromium only

README.md what npm shows; ACCESSIBILITY.md, SECURITY.md, CONTRIBUTING.md, GLOSSARY.md,
CODE_OF_CONDUCT.md beside it

Expand All @@ -266,6 +283,11 @@ skills/ agent skills, one directory per skill, at the root bec
`npx skills add <owner/repo>` looks: h5p-verify (when to run the verifier and how
to read its report), h5p-player-setup (putting the player on a site), h5p-normalize (when
a package needs rewriting to stream, and how to read the dry run)
and h5p-author (text-only Multiple Choice and Question Set from a prompt:
a quiz JSON source, the installed pack's semantics and runtime dependency
closure, then the existing verifier and screenshot review; its bundled
scripts/build-quiz.mjs resolves dependencies from the caller's project,
and is tested from apps/skills)

api/no-range.js the Vercel function that stands in for a host without Range on the demo
vercel.json the deployment: build command, the /no-range rewrite, caching and security headers
Expand Down Expand Up @@ -370,6 +392,12 @@ cmi5 page also against CATAPULT (`pnpm cmi5:catapult`). Where a page's test was
package's behaviour, the test moved into the package: the embed page asking before it plays a
package that needs its own code, and `resizer.js` answering a frame that loaded before it, are in
`packages/embed/tests/site.test.ts`; the cmi5 page's were already in `packages/cmi5/tests/`.
The skills' scripts are source too, tested from `apps/skills`, a project of their own (2026-10-23,
the owner's choice). h5p-author's tests were first in the demo, which had the pack and zip.js
installed, and in the verifier's tests, and the playback test played the quiz through the
installable app. It plays it in the verifier's preview now, the page the skill hands a person to
review it in, and in Chromium only, where in the demo the `engines` job ran it in Firefox and
WebKit too; the player's own suite covers the engines.

The app's tests follow the same variable (`apps/demo/tests/engine.ts`; `tests/harness.ts`
starts the dev server and the second-origin package host and waits on the element for all of
Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ Thank you for contributing to `h5p-offline-player`.
## Before you start

This repository is a pnpm workspace containing the player, the H5P runtime, the
library bundle, the normalizer, the verifier, the cmi5 package, the embed site writer and the
demo application. Read the
library bundle, the normalizer, the verifier, the cmi5 package, the embed site writer, the
demo application and a project that tests the agent skills' scripts. Read the
[development guide](./docs/development.md) before making changes. It explains
the workspace layout, generated assets, and the commands that apply to each
package.
Expand Down
13 changes: 11 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ something else.
- **Comes with tools for pipelines.** [`h5p-verify`](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/verify.md) plays a package headless
and says whether it works, [`h5p-normalize`](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/streaming-video.md) rewrites one so its
video streams, and [`h5p-embed`](https://github.com/missing-elements/h5p-offline-player/tree/main/packages/embed#readme)
writes the embed site. The [agent skills](#agent-skills) cover all three.
writes the embed site. The [agent skills](#agent-skills) cover those workflows and quiz authoring.
- **Is tested where it runs.** CI runs the browser tests in Chromium, Firefox and WebKit on every
change, and plays every content type in the library pack, untrusted and trusted, on each change to
the player, the runtime or the pack, and every week.
Expand Down Expand Up @@ -286,8 +286,17 @@ is an example.
npx skills add missing-elements/h5p-offline-player
```

[`h5p-author`](https://github.com/missing-elements/h5p-offline-player/tree/main/skills/h5p-author)
turns a prompt or lesson into a text-only Multiple Choice or Question Set: a portable helper
builds the `.h5p` against the installed library pack, and the agent verifies it in the real
player and reviews the screenshot before handing it over. Works with Claude Code and other
agents with filesystem and command access; no provider API key or H5P server is needed.
For example: "Create five practice questions from this lesson for new employees, with
explanatory feedback. Use h5p-author and verify the result." Needs Node 22 or later.

`h5p-player-setup` puts H5P on a site, `h5p-normalize` fixes packages whose video will not
stream, `h5p-verify` checks a generated package plays.
stream, and `h5p-verify` checks a generated package plays. A verifier pass checks startup and
rendering, not whether the answers are right or the activity is accessible.

## Development

Expand Down
18 changes: 18 additions & 0 deletions apps/skills/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{
"name": "@missing-elements/h5p-skills",
"private": true,
"type": "module",
"scripts": {
"test": "pnpm --filter @missing-elements/h5p-offline-player build && vitest run",
"typecheck": "tsc -p tsconfig.json"
},
"devDependencies": {
"@missing-elements/h5p-libraries": "workspace:*",
"@missing-elements/h5p-verify": "workspace:*",
"@types/node": "^26.6.5",
"@zip.js/zip.js": "^2.24.0",
"playwright": "^1.64.1",
"typescript": "^7.0.2",
"vitest": "^5.0.5"
}
}
100 changes: 100 additions & 0 deletions apps/skills/tests/author-playback.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
import { mkdtemp, readFile, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join, resolve } from 'node:path'
import { chromium, type Browser, type Page } from 'playwright'
import { afterAll, beforeAll, expect, it } from 'vitest'
import { previewPackage } from '../../../packages/verify/lib/preview.mjs'
import { buildQuiz, type Quiz } from '../../../skills/h5p-author/scripts/build-quiz.mjs'

const project = resolve(import.meta.dirname, '..')
// The pack this project installed, named to the preview as `--libraries` names a copy of its parts.
const parts = resolve(project, 'node_modules/@missing-elements/h5p-libraries/parts')
const source: Quiz = JSON.parse(await readFile(resolve(project, '../../skills/h5p-author/assets/phishing-scenarios.json'), 'utf8'))
let dir: string
let file: string
let browser: Browser

beforeAll(async () => {
dir = await mkdtemp(join(tmpdir(), 'h5p-author-interaction-'))
file = join(dir, 'scenarios.h5p')
await buildQuiz(source, file, project)
browser = await chromium.launch()
})
afterAll(async () => {
await browser?.close()
if (dir) await rm(dir, { recursive: true, force: true })
})

type Player = HTMLElement & { state: string; untrusted: boolean }
type ResultsWindow = Window & typeof globalThis & { authorFinished: unknown[] }

async function finished(page: Page, count: number) {
await page.waitForFunction(count => (window as ResultsWindow).authorFinished.length === count, count)
return page.evaluate(() => (window as ResultsWindow).authorFinished.at(-1))
}

async function attempt(page: Page, correctQuestions: number, previousResults: number) {
const frame = page.frameLocator('h5p-player iframe')
for (let i = 0; i < source.questions.length; i++) {
const question = source.questions[i]
const candidates = question.answers.filter(answer => i < correctQuestions ? answer.correct : !answer.correct)
const selected = question.multipleAnswers ? candidates : candidates.slice(0, 1)
for (const answer of selected) {
await frame.getByRole(question.multipleAnswers ? 'checkbox' : 'radio').filter({ hasText: answer.text }).click()
}
await frame.getByRole('button', { name: /^Check the answers/ }).click()
for (const answer of selected) {
if (!answer.feedback) throw new Error('The scenario example must explain every answer')
await frame.getByText(answer.feedback, { exact: true }).waitFor({ state: 'visible' })
}
// Sub-question answers must not finish the parent Question Set.
expect(await page.evaluate(() => (window as ResultsWindow).authorFinished.length)).toBe(previousResults)
await frame.getByRole('button', { name: i === source.questions.length - 1 ? 'Finish' : 'Next', exact: true }).click()
}
}

// In the verifier's preview, the page the skill's review hands a person: trusted, and untrusted
// against the installed pack, as a site that did not make the quiz plays it.
it.each([false, true])('plays every scenario in the preview across the 80% threshold and retries to 100% (untrusted: %s)', async untrusted => {
const preview = await previewPackage({ file, port: 0, untrusted, libraries: untrusted ? parts : undefined })
const page = await browser.newPage({ viewport: { width: 1100, height: 850 } })
const errors: string[] = []
page.on('pageerror', error => errors.push(error.message))
try {
await page.goto(`${preview.url}/`)
await page.waitForFunction(() => ['ready', 'error'].includes((document.querySelector('h5p-player') as Player).state), null, { timeout: 60_000 })
expect(await page.locator('h5p-player').evaluate(player => [(player as Player).state, (player as Player).untrusted])).toEqual(['ready', untrusted])
await page.locator('h5p-player').evaluate(player => {
const results: unknown[] = []
Object.defineProperty(window, 'authorFinished', { value: results })
player.addEventListener('finished', event => {
if (event instanceof CustomEvent) results.push(event.detail.statement)
})
})

await attempt(page, 6, 0)
expect(await finished(page, 1)).toMatchObject({
verb: { id: 'http://adlnet.gov/expapi/verbs/completed' },
result: { completion: true, success: false, score: { raw: 9, max: 12, scaled: 0.75 } },
context: { revision: expect.stringMatching(/^sha256:[0-9a-f]{64}/) }
})
const frame = page.frameLocator('h5p-player iframe')
await frame.getByRole('button', { name: 'Retry', exact: true }).click()
await attempt(page, 7, 1)
expect(await finished(page, 2)).toMatchObject({
result: { completion: true, success: true, score: { raw: 10, max: 12, scaled: 0.8333 } }
})
await frame.getByRole('button', { name: 'Retry', exact: true }).click()
await attempt(page, source.questions.length, 2)
expect(await finished(page, 3)).toMatchObject({
result: { completion: true, success: true, score: { raw: 12, max: 12, scaled: 1 } }
})
await frame.getByRole('button', { name: 'Show solution', exact: true }).click()
await frame.getByText(source.questions[0].answers[2].text, { exact: true }).waitFor({ state: 'visible' })
expect(await frame.getByRole('button', { name: /^Check the answers/ }).count()).toBe(0)
expect(errors).toEqual([])
} finally {
await page.close()
preview.close()
}
})
53 changes: 53 additions & 0 deletions apps/skills/tests/author-verify.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import { mkdtemp, readFile, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join, resolve } from 'node:path'
import { verifyPackage } from '@missing-elements/h5p-verify'
import { afterAll, beforeAll, expect, it } from 'vitest'
import { buildQuiz, type Quiz } from '../../../skills/h5p-author/scripts/build-quiz.mjs'

const project = resolve(import.meta.dirname, '..')
// The pack this project installed, named to the check as `--libraries` names a copy of its parts.
const parts = resolve(project, 'node_modules/@missing-elements/h5p-libraries/parts')
const skill = resolve(project, '../../skills/h5p-author')
const example: Quiz = JSON.parse(await readFile(join(skill, 'assets/quiz.json'), 'utf8'))
const scenarios: Quiz = JSON.parse(await readFile(join(skill, 'assets/phishing-scenarios.json'), 'utf8'))
let dir: string
const files = new Map<string, string>()

beforeAll(async () => {
dir = await mkdtemp(join(tmpdir(), 'h5p-author-verify-'))
for (const kind of ['multiple-choice', 'question-set'] as const) {
const source: Quiz = { ...example, kind, questions: kind === 'multiple-choice' ? [example.questions[0]] : example.questions }
const file = join(dir, `${kind}.h5p`)
await buildQuiz(source, file, project)
files.set(kind, file)
}
const file = join(dir, 'scenarios.h5p')
await buildQuiz(scenarios, file, project)
files.set('scenarios', file)
})
afterAll(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })

// Step 4 of the skill: the check, through the verifier's published API.
it.each([
['multiple-choice', false],
['multiple-choice', true],
['question-set', false],
['question-set', true],
['scenarios', false],
['scenarios', true]
])('plays authored %s (untrusted: %s) without warnings', async (kind, untrusted) => {
const report = await verifyPackage({
file: files.get(kind)!,
untrusted,
libraries: untrusted ? parts : undefined,
settle: 500
})
expect(report.verdict, JSON.stringify(report)).toBe('pass')
expect(report.warnings).toEqual([])
expect(report.errors).toEqual([])
expect(report.state).toBe('ready')
expect(report.untrusted).toBe(untrusted)
expect(report.revision).toMatch(/^sha256:[0-9a-f]{64}(; libraries sha256:[0-9a-f]{64})?$/)
expect(report.rendered?.text).toBeGreaterThan(100)
}, 60_000)
Loading
Loading