diff --git a/AGENTS.md b/AGENTS.md index a06eb92d..ac657cb2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 @@ -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 - `/content/`, 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 `/content/`, relative to nothing). The core's own `H5P.getPath` reads `contents['cid-'].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 @@ -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, diff --git a/docs/resume.md b/docs/resume.md index ad2c3f7a..066d7a94 100644 --- a/docs/resume.md +++ b/docs/resume.md @@ -7,7 +7,7 @@ the content picks up where it was: ``` -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 diff --git a/packages/player/tests/browser/resume.test.ts b/packages/player/tests/browser/resume.test.ts index aa9a63ce..49f6c0d0 100644 --- a/packages/player/tests/browser/resume.test.ts +++ b/packages/player/tests/browser/resume.test.ts @@ -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 } } + 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: '' }) diff --git a/packages/runtime/src/frame-boot.ts b/packages/runtime/src/frame-boot.ts index 23bead97..f71ba3d9 100644 --- a/packages/runtime/src/frame-boot.ts +++ b/packages/runtime/src/frame-boot.ts @@ -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/` 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/` 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 = {