Skip to content

feat(h5p-author): build in a page, from ./browser, with the core at ./core (#108) - #115

Merged
alekswebnet merged 2 commits into
mainfrom
feat/author-browser-entry
Nov 2, 2026
Merged

alekswebnet merged 2 commits into
mainfrom
feat/author-browser-entry

Conversation

@alekswebnet

Copy link
Copy Markdown
Contributor

Closes #108.

What it adds

The author package gets three entries:

Entry For Holds
. Node the core, and Node's buildPackage, openPack and schemaOf, as before
./core anything what needs neither Node nor a page: the generator, loadLibraries, packageLibraries, checkContent, the text rules, SourceError
./browser a page or a Tauri window the core, and a page's openPack and buildPackage

They are subpaths, not the browser condition. TypeScript ignores conditions unless a project sets customConditions, so a page importing . would get the page's code typed by Node's declarations. The two buildPackages also take different arguments.

import { pack } from '@missing-elements/h5p-libraries'
import { buildPackage, openPack } from '@missing-elements/h5p-author/browser'

const libraries = await openPack(pack)
const { blob, notes } = await buildPackage(source, { libraries, files: { 'volga.png': input.files[0] } })

One build, two environments

lib/build.mjs now holds what both builds do. composePackage is the old buildPackage body, moved unchanged except that it is handed a media store. writePackage writes the manifest, the libraries and the content into a zip.js writer. lib/node.mjs is the only module that imports node:: the pack from disk, a source's files beside it, downloads in a temporary folder, the output path and the normalizer. lib/browser.mjs is the page's. A test holds the entries' imports to that.

Three things follow:

  • A part is read whole and hashed with crypto.subtle, in Node too. Node's reader by range went: the largest part is 2.8 MB, and the hash already read every byte. A page can't read by range anyway: SHA-256 needs every byte, crypto.subtle.digest takes no stream, and jsDelivr cuts ranges from its compressed copy.
  • What a page names the pack by. The pack export is taken as the page's bundler emitted it. An address of a parts/ folder has its index.json held to the player's shape by packLibrariesIn, which the player's ./plan now exports. That rule is http(s) only, as the player reads a copy, so a Tauri window on macOS (tauri://) gives the export instead.
  • Media come as Files or Blobs, by the names the source gives them. They are stored with their size and CRC in their local headers, through zip.js's pass-through, as embed's SCORM writer has done since h5p-embed --scorm: SCORM Cloud cannot import the zip (data descriptors on stored entries) #92. Written into a stream, zip.js would put them in a data descriptor instead. An mp4 goes in as given: moving its index to the front stays the normalizer's, in Node.

A page needs a secure context for crypto.subtle and crypto.randomUUID. The generator now takes ids from globalThis.crypto. openPack and buildPackage refuse outside a secure context with a message that says so. A failed download of a file named by address in a page gets a CORS hint, since most image hosts send no Access-Control-Allow-Origin.

Reused, not copied

  • The player's ./plan: packLibrariesIn, extended to export it.
  • The normalizer's CRC-32, extended with ./crc32: Node resolves it to zlib's, anything else to a table with no Node import (lib/crc32-table.mjs). Embed's SCORM writer imports it now, and its copy is gone. ./crc32 is added to docs/compatibility.md, since embed and h5p-author take it through a ^ range.
  • Embed's way of storing an entry with a complete header (h5p-embed --scorm: SCORM Cloud cannot import the zip (data descriptors on stored entries) #92).

Where this differs from the issue

  • ./core exports what . exported before minus Node's build and pack. The issue also listed translateDefaults, quizSource and quizProblems. They stay internal: loadLibraries already gives the translated defaults, and buildPackage takes the quiz format itself.
  • The second acceptance criterion, creator's Create on the core with its authoring.test.ts passing, is in embed-my/creator. It can be done once this is released.

Release

The order becomes player (./plan with packLibrariesIn), then normalizer (./crc32, a minor), then embed and h5p-author. Both publish guards check the normalizer's ./crc32 on npm. Embed's guard is renamed scripts/check-published.mjs, since it checks two packages now.

Checked

  • Acceptance, in Chromium (tests/browser/page.test.ts): H5P.Blanks and a Question Set with a picture drawn on a canvas, built in the page (0.9 and 1.3 MB). The bytes go to Node through a Vitest command, where verifyPackage plays each untrusted against the pack: a pass, no warnings, and nothing changed by the content check (contentCheck { notes: [], changes: [] }).
  • The page's build in Node (tests/page.test.ts, 9 tests):
    • H5P.Blanks comes out file for file as Node's build writes it.
    • The stored picture's local header carries method 0, its size and its CRC, with no descriptor flag.
    • Missing files are named, along with the files that were given.
    • A damaged part is refused.
    • An address's index drops what the player drops.
    • A CORS failure gets the hint.
    • The secure-context refusal works.
    • The entries' imports hold.
    • I broke the CRC, the pass-through and the index check in turn, and each made a test fail.
  • Author: 139 tests, 10 new. The 129 that were there pass unchanged except one that builds a MediaStore directly.
  • Elsewhere:
    • skills project: 73 (every type file's example built, checked as saved, played both ways);
    • embed: 48;
    • normalizer: 22, 2 new;
    • player unit tests: 364;
    • the demo's sweep-content test: 5;
    • the workspace typecheck, the published declarations of all three entries included.
  • Content-type sweep: not run locally. CI runs it on this PR, since generator.mjs changed (ids from globalThis.crypto).

The author package's test script now builds the player and runs the Chromium project too. test:unit runs the Node project alone. CI's test job and the weekly pack refresh already install Chromium before it.

🤖 Generated with Claude Code

…/core (#108)

The package has three entries now: `.` for Node, `./core` for what needs
neither Node nor a page, and `./browser`, the core and a page's
`openPack` and `buildPackage`. One build runs in both: lib/build.mjs
composes and writes what a package holds, lib/node.mjs is the only
module that imports `node:` (the pack from disk, files beside the
source, the output path, the normalizer), and lib/browser.mjs reads the
pack a page can reach, takes `File`s by name and returns a `Blob`.

- A part is read whole and hashed with crypto.subtle in Node too; the
  range reader went.
- A page's pack is the `pack` export as emitted, or a parts folder's
  address, whose index is held to the player's shape by
  `packLibrariesIn`, which the player's ./plan now exports.
- Media are stored with their size and CRC in their local headers, as
  embed's SCORM writer stores its entries. The CRC is the normalizer's,
  exported as ./crc32 (zlib's for Node, a table elsewhere); embed's copy
  went, and both publish guards check that ./crc32 is on npm.
- Ids come from globalThis.crypto, so the generator runs in a page.

Tests: the page's build in Node against Node's build, and in Chromium,
its packages played untrusted by the verifier through a Vitest command.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… a partial replace

The page build's first test compared two builds' 138 files with toEqual,
byte by byte through Vitest's deep equality: 3.6 s here, 9.6 s on CI,
past the 5 s default. It compares each file's SHA-256 now, in 0.24 s, and
a difference still names the file.

CodeQL's js/incomplete-sanitization on embed's publish guard: the
package name's slash is replaced with replaceAll.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@alekswebnet
alekswebnet merged commit 3172a0d into main Nov 2, 2026
9 checks passed
@alekswebnet
alekswebnet deleted the feat/author-browser-entry branch November 3, 2026 11:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

h5p-author: an entry that runs in a browser

2 participants