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
24 changes: 18 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -1177,6 +1177,18 @@ element, and the element acts. That relay is why `frame-document.ts` has a `mess
`saveFreq` the frame is handed, ten seconds by default, read once per load the same way; the
CMS plugins default to thirty and make it a setting. `resume.test.ts`
drives all of it through the fixture content type, which counts presses of Complete.
**The content's id is the same on every load of a package** (#127, 2026-11-04), as a site's row
number is: a number made from the package's id, twelve of its hex digits (`contentIdOf` in the
boot script), so that it names what the saved state is kept under. Content types keep places by
it: Interactive Book stores its chapter under it, in its state and in the page's address
(`urlFragments`, `h5pbookid`), and takes it back only when the id matches; Cornell Notes keeps a
copy of its notes in `localStorage` under it, read only for a number (`typeof … === 'number'`,
which is why the id is one, and why it has twelve digits, which a double holds exactly: the core
reads it back through jQuery's `.data()`, which turns a string of digits into a number). Until
then it was random, as h5p-standalone gave it, so every book reopened on its first chapter, with
its answers, in any `resume` mode and in the SCORM zip, measured in Moodle and in the player.
One consequence: two players of one book on one page share the address's chapter and turn
pages together, as two copies of one content do on a site.
- **`libraries="pack"` is the library pack the release pins, and the H5P hub is not asked.**
Decided on 2026-10-10. H5P Group moved the hub from `api.h5p.org` to `hub-api.h5p.org` in 2026,
with a newer catalogue behind it; the new host sends no `Access-Control-Allow-Origin` header, so
Expand Down Expand Up @@ -1482,8 +1494,8 @@ element, and the element acts. That relay is why `frame-document.ts` has a `mess
- **`H5P.getContentPath` answers the content's own folder.** The core builds it as
`H5PIntegration.url + '/content/' + id`, which on a site is the H5P folder and each content's
own below it; here the content is the package's `content/`, one level below `url`, which the
boot script sets to the package's root (h5p-standalone set the content id, so it answered
`<id>/content/<id>`, relative to nothing). The core's own `H5P.getPath` reads
boot script sets to the package's root (h5p-standalone set the content id, a random one then,
so it answered `<id>/content/<id>`, relative to nothing). The core's own `H5P.getPath` reads
`contents['cid-<id>'].contentUrl` first, which the boot script sets, and it makes
`getContentPath` do the same (2026-10-13). IFrame Embedder is the one
content type in the pack that asks, for a page the package carries — so it showed nothing, in
Expand Down Expand Up @@ -2506,10 +2518,10 @@ one row each; an LMS added here gets a row there.
compressed, base64 costing a third. The 12-chapter book read to its last chapter in Moodle wrote
996 characters and came back with its chapters' state, and on its first chapter: Interactive
Book takes its saved place (`urlFragments`, with `h5pbookid`) back only when that id is the
content id, which the boot script draws at random on every load (`integrationFor`), so no book
returns to its chapter in any `resume` mode, a runtime bug outside #124 (#127), measured the same day
in the plain player with `resume="device"`. Two corpus books carry Interactive Book 1.3, which
keeps no state at all.
content id, which the boot script drew at random on every load, so no book returned to its
chapter in any `resume` mode, measured the same day in the plain player with `resume="device"`
too. Fixed in the runtime by #127 (the content's id under *The saved state never leaves the
page*). Two corpus books carry Interactive Book 1.3, which keeps no state at all.
- **Outside an LMS** the page finds no API, plays the package and reports nothing.
- **Frappe LMS plays it too, and records less.** Checked on 2026-10-30 against Frappe LMS's
`develop` branch in its own Docker setup, as an enrolled student in Chrome, with the demo's quiz,
Expand Down
2 changes: 1 addition & 1 deletion docs/resume.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ the content picks up where it was:
<h5p-player src="course.h5p" resume></h5p-player>
```

The content saves what its `getCurrentState()` returns — the slide reached, the answers given,
The content saves what its `getCurrentState()` returns — the slide or chapter reached, the answers given,
the position in a video — every ten seconds, three seconds after a `completed` or `progressed`
statement, and as the frame goes away. `save-interval` sets the seconds between saves: the H5P
plugins default to 30, which suits `resume="host"` with each save sent to a server. A content
Expand Down
16 changes: 16 additions & 0 deletions packages/player/tests/browser/resume.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,22 @@ describe('resume', () => {
expect((await completeAndSave(again)).data).toBe('{"clicks":3}')
})

it('gives the content the same id on every load of a package, a number as a site gives one', async () => {
// Interactive Book keeps its place under the content's id and takes it back only when the id
// matches, and Cornell Notes reads the copy it keeps by the id only for a number (#127). Until
// then the id was random on every load.
const contentId = (player: H5PPlayerElement) => {
const view = frameWindow(player) as unknown as { H5P: { instances: Array<{ contentId: unknown }> }; H5PIntegration: { contents: Record<string, unknown> } }
return { instance: view.H5P.instances[0].contentId, key: Object.keys(view.H5PIntegration.contents)[0] }
}
const player = await play(FIXTURES.basic)
const first = contentId(player)
expect(first.instance).toBe(parseInt((player.pkgId as string).slice(0, 12), 16))
expect(first.key).toBe(`cid-${first.instance}`)
expect(contentId(await play(FIXTURES.basic))).toEqual(first)
expect(contentId(await play(FIXTURES.english)).instance).not.toBe(first.instance)
})

it('saves every ten seconds by default, and as often as save-interval asks', async () => {
type Integration = Window & { H5PIntegration?: { saveFreq?: unknown } }
const standard = await play(FIXTURES.basic, { resume: '' })
Expand Down
24 changes: 19 additions & 5 deletions packages/runtime/src/frame-boot.ts
Original file line number Diff line number Diff line change
Expand Up @@ -224,15 +224,29 @@ var flag = function (value: boolean | undefined, otherwise: boolean) {
// licence names from them.
var translations = coreTranslations(window.H5PRuntimeL10n, config.language);

/**
* The content's id. A site gives each content its row's number, the same on every load, and
* content types rely on both: Interactive Book keeps its place under the id, in its saved state and
* in the address, and takes it back only when the id matches (#127); Cornell Notes reads the copy
* of its notes it keeps by the id only when the id is a number. So a number made from the package's
* id, which names the same package on every load and is what the learner's state is kept under:
* twelve of its hex digits, which a double holds exactly, since the core reads the id back through
* jQuery's `.data()`, which turns a string of digits into a number. Until #127 it was random, as
* h5p-standalone gave it, and nothing that kept a place by it ever found it again.
*/
var contentIdOf = function (pkgId: string): number {
return parseInt(String(pkgId).slice(0, 12), 16) || 1;
};

/**
* The core's settings for this one content, as a site's H5P plugin writes them and as
* h5p-standalone wrote them here before the core was vendored. A random content id, as it gave.
* `url` is the package's root rather than that id: the core joins it with `/content/<id>` only
* where a content's own `contentUrl` is missing, and `H5P.getContentPath`, which joins it always,
* is answered from `contentUrl` below.
* h5p-standalone wrote them here before the core was vendored. `url` is the package's root rather
* than the content's id: the core joins it with `/content/<id>` only where a content's own
* `contentUrl` is missing, and `H5P.getContentPath`, which joins it always, is answered from
* `contentUrl` below.
*/
var integrationFor = function (load: LibraryLoad, jsonContent: string, preload: UserDataPreload | null): Integration {
var contentId = Math.random().toString(36).substring(2, 9);
var contentId = contentIdOf(config.pkgId);
var base = config.h5pJsonPath;
var file = function (path: string) { return base + '/' + path; };
var content: IntegrationContent & Record<string, unknown> = {
Expand Down
Loading