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
80 changes: 79 additions & 1 deletion design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ already holds text to the content check's rules, from the pack an untrusted chec
`apps/skills` plays every example untrusted too. Measured on a five-question quiz, at four
characters a token: `content.json` was about 3,470 tokens to write by hand, after reading 3,900 to
9,500 of a type's semantics; the source is 1,000 to 1,800 tokens, written from a type file of 200
to 3,000. Fourteen things the code does not say by itself:
to 3,000. Eighteen things the code does not say by itself:

- **One generator, three ways to run it.** The third, `saved`, checks content as H5P stores it
(*Saved content is checked as the build checks what it writes*, below). `ContentGenerator` was the sweep's
Expand Down Expand Up @@ -319,6 +319,84 @@ to 3,000. Fourteen things the code does not say by itself:
where the verifier's preview opens: a real browser, in which the player runs as it is, video
included. The owner chose the panel, with media to come, and the card was not built.

- **A problem says what to write, and what is in the wrong place is checked all the same**
(2026-11-10, #172). The owner gave the skill to Gemini in Chrome, which could not build a simple
Interactive Book and quoted `params.chapters: has 0 items; it takes at least 1`. A chat there has
the skill's text, no type file and nothing to run, so it learns a type's shape from the build's
problems alone. Measured that way with the weakest Claude model, Haiku 5.5: SKILL.md's text, each
reply built as the build page builds it, its problems pasted back in the page's words, up to four
rounds; an Interactive Book, a Course Presentation, a Column, a Question Set and a Branching
Scenario, three runs each, the same 15 first replies under each set of messages. With 0.6.0's
messages 3 built at once, the Question Sets, 8 by the second round, 12 by the third, 13 by the
fourth, and two scenarios never. What cost the rounds was a type's levels, not its fields:
- Sub-content in the place of the group that holds it, `{ "library", "params" }` where a
Column's item is `{ "content": { … } }`, a slide's element `{ "action": { … } }` and a
scenario's node `{ "type": { … } }`: 9 of the 24 failed rounds, three or four problems an item,
one of them a list of 35 libraries, none saying what to write.
- A field a level above its group, `params.slides` for `params.presentation.slides`: the build
said it was no field there and checked nothing of what was written in it, so the next round
found what was wrong inside, an `<h1>` a slide's text does not take.
- A book's chapters written as pages, `{ "title", "content": [ … ] }`, with no H5P.Column around
them, in two of three books: "expected sub-content", and then "has 0 items", which the last
check counted after the generator had refused the chapters and which was not so.
- "expected sub-content, { "library": "H5P.BranchingQuestion" … }" for a field that takes seven
libraries: the first read as the one to write, and a scenario's texts came back as questions.

So the generator says each such thing once, by its path and with what to write there, then puts
what was written where it belongs and checks it, naming what is wrong inside by where the source
has it (`moved`, by which the build's last check names what it finds too). The one library a
field takes is loaded whether or not a source names it, which is what reads a chapter without
its Column as the Column's parameters. What the last check says of a list an item of which was
refused is left out, the list being another than the one written (`shortened`). A field that
takes several libraries names them all. A scenario's question with no alternatives is reported
as that and not as a loop besides. And a problem's list of fields names those an author writes,
the interface texts as one: a book's was 39 names long. With these messages the same first
replies built 12 by the second round and all 15 by the third, and every package built under
either set plays (h5p-verify). The first wording, "is sub-content, which goes in the field
content here", did worse than the three problems it replaced: a Column's list and its items'
field are both `content`, one run sent the same source again and one made the list an object.
So the problem names the item and shows it whole, `write params.content[0] as { "content": … }`.
Only an object or a list, a text, a number or a flag whose name one group below has, in a field
an author writes that takes such a value, is taken to belong there; an interface text is none,
since a question's text sent to a label of its name would build and read wrong. And an object
goes to a group only where it writes one of the group's fields, not one of its interface texts:
a Game Map's `map`, written for the picture, was first sent to `behaviour.map`, the map's labels
and fog, a name and no more, and an object that holds only a group's `l10n` is no proof of it.
- **The package carries the skill's type files** (2026-11-10, #172). In the same measurement, what
did most was no message: with the type files pasted back beside the first problems, the content
type's and those of the libraries the source names, all 15 built by the second round, in two
runs of the twelve that had failed. A chat with the skill has those files; one in a browser has
the build page, which has the package and no skill. So `prepack` copies
`skills/h5p-author/references/types/*.md` into the package, `references/types/<Type>.md`, each
an export, for the page to hand over with a source's problems. They stay the skill's, at the
repository's root where `npx skills add` looks, written by `sync:skill` as before; the copy is
not in git, and `build.test.ts` holds it to the skill's files, file for file.

The same test on the 23 other content types the skill lists says how far each thing reaches:
two runs each, 46 first replies, each built package checked against what its task asked for.
16 were right at once. By the fourth round 35 were right under 0.6.0's messages and 36 under
the new ones, which is no difference: there a weak model does not misplace what it knows, it
does not know a type's names (`options`, `sequenceImages`, `questionnaireElements`) or its rules
(the right answer first, a card a pair), and a problem gives it one level's names a round. 9
and 7 packages built and were not what was asked, a question's feedback left out once no field
took it. With the type files handed back, 42 were right by the second round and 43 by the third,
and none stayed unbuilt; three had built at once and wrong, with no problem to hand a file back
with, and one source named a type the pack has not, which no file answers until the next round
names a real one. With the type's file before the first reply, one run of each of the 28 types,
all 28 were right at once and play. So the messages are for a type's levels, and the type's file
is what lets a weak model write any type: the page hands it back, the skill gives its address.
- **The skill says where a container holds its sub-content** (2026-11-10, #172). The one thing in
SKILL.md that repeats a type file, for the chat that cannot read one. Its line on sub-content
names the three commonest places: an item of H5P.Column's `content` is
`{ "content": <sub-content> }`, a slide's element `{ "action": <sub-content> }` in
`presentation.slides[].elements`, a book's chapter an H5P.Column. In the measurement above no
first reply for a book, a page or slides built, 0 of 9; with that sentence in the skill's text
all 9 built at once and play. A scenario, which it does not name, still took a round of
problems, and so do the six other listed types that hold content (Accordion, Questionnaire,
Interactive Video, Image Hotspots, Image Choice, Game Map): of 12 first replies 2 were right at
once with the sentence and 2 without, the Accordions. The skill gives the type files' address
on GitHub too, for a chat that has its text and can open a link.

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.
11 changes: 7 additions & 4 deletions design/layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,9 +190,10 @@ packages/author/ @missing-elements/h5p-author — a playable .h5p of an
`packageLibraries`, a package's own over the pack's (#107); no Node
import of its own, nor has lib/source-error.mjs, `SourceError` (#106)
lib/generator.mjs `ContentGenerator`: content from a type's `semantics.json`, authoring
(every written value checked as the editor's form would), lenient, as
the sweep runs it, or saved, as `checkContent` runs it; moved out of the
demo on 2026-11-01 (#100)
(every written value checked as the editor's form would, and what is
written in the wrong place said once, put where it belongs and checked
there, #172), lenient, as the sweep runs it, or saved, as `checkContent`
runs it; moved out of the demo on 2026-11-01 (#100)
lib/types.mjs what the editor's own widgets set and check, per content type: Course
Presentation's layout, Interactive Video's placement, Branching
Scenario's paths, Game Map's stages, Find the Hotspot's areas
Expand All @@ -205,7 +206,9 @@ packages/author/ @missing-elements/h5p-author — a playable .h5p of an
scripts/ sync-skill.mjs writes the skill's type files' generated sections from the
pack (`pnpm --filter @missing-elements/h5p-author sync:skill`);
check-pack-published.mjs, the publish guard for the pinned pack and player,
and the normalizer's `./crc32`
and the normalizer's `./crc32`; copy-type-files.mjs, `prepack`'s copy of
the skill's type files into `references/types/`, which the package
carries and git does not (#172)
tests/ node tests: the generator, text and translations, layouts and schema, the
loader, builds with media from disk and a local server, the command, the
quiz format, the check of saved content, the demo's packages among it, and
Expand Down
15 changes: 15 additions & 0 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,16 @@ h5p-author: The source has 2 problems:
params.behaviour.sideways: is not a field here; the fields are enableRetry, enableSolutionsButton, …
```

What is written in the wrong place is said once, with what to write, and still checked, so that
what is wrong inside it comes in the same round:

```
h5p-author: The source has 3 problems:
params.slides: is a field of presentation, not of this level: write params.presentation.slides
params.slides[0].elements[0]: is sub-content, but here it goes inside an object, in its field action: write params.slides[0].elements[0] as { "action": { "library": "H5P.AdvancedText", "params": { … } } }
params.slides[0].elements[0].params.text: has <h1>, which this field does not take; it takes <a> <br> …
```

The quiz format the h5p-author skill published first (`{ "kind": "question-set", "questions": [ … ] }`)
is still taken, for a Multiple Choice question or a Question Set of them.

Expand All @@ -108,6 +118,11 @@ H5P.TrueFalse 1.8: True/False Question
`--all` adds the interface texts; `--markdown` prints the section the skill's type files carry.
An unknown name lists the pack's content types.

The package carries those type files too, as the release has them:
`@missing-elements/h5p-author/references/types/H5P.TrueFalse.md` is the type's notes, an example and
these fields. A page that builds for a chat with no skill beside it hands them over with a source's
problems, as the [build page](https://missing-elements.github.io/h5p/build/) does.

## A content type's bundle

```bash
Expand Down
18 changes: 15 additions & 3 deletions packages/author/lib/build.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -190,11 +190,23 @@ export async function composePackage(source, pack, media) {
// what the editor's widgets set and check what they would not let pass. Where the source has a
// problem already, the check finds the same one again, or the gap it left: a value missing
// where the generator refused what was written inside it. Only what it finds elsewhere is added.
// Since #172 it is named by where the source has it, which is another place than the content's
// for what the generator moved to its field; such a move is a problem of the source's, but
// nothing was refused there, so what the check finds inside it is added like any other. And
// what it says of a list an item of which was refused, or of anything in one, is left out: the
// list it counted is shorter than the one written, its items at other indices, so a book whose
// chapters were all refused had "0 items" besides.
const checked = checkContent({ entries, main: mainLibrary, translations }, { type: libraryString(mainLibrary.library), params: generated })
const fromSource = [...problems]
const known = (/** @type {Problem} */ problem) => fromSource.some(({ path }) => path === problem.path || inside(problem.path, path) ||
(inside(path, problem.path) && valueAt(checked.params, problem.path) === undefined))
for (const problem of checked.problems) if (!known(problem)) problems.push(problem)
const moves = new Set(generator.moved.map(({ from }) => from))
const inSource = (/** @type {string} */ path) => generator.moved.reduce((at, { from, to }) => at === to || inside(at, to) ? from + at.slice(to.length) : at, path)
const shortened = (/** @type {string} */ path) => generator.shortened.some((list) => path === list || inside(path, list))
for (const { path: inContent, message } of checked.problems) {
const path = inSource(inContent)
const known = fromSource.some((problem) => problem.path === path || (inside(path, problem.path) && !moves.has(problem.path)) ||
(inside(problem.path, path) && valueAt(checked.params, inContent) === undefined))
if (!known && !shortened(path)) problems.push({ path, message })
}
for (const added of checked.notes) if (!notes.some(({ path, message }) => path === added.path && message === added.message)) notes.push(added)
if (problems.length) throw new SourceError(problems)
const content = checked.params
Expand Down
Loading
Loading