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
15 changes: 14 additions & 1 deletion design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -377,6 +377,18 @@ text to the content check's rules, and `apps/skills` plays every example untrust

`*10:30*` as written is not refused: it is a tip to the library and may be one to its author.
Over the 94 real packages of the owner's corpus and the demo, the two checks report nothing.
- **What builds and is almost surely a mistake is a note** (#241, item 4 of #219). H5P allows
each, so none is a problem, and nothing is judged: no answer marked correct (Multiple Choice's
answers, Multimedia Choice's options; Find the Hotspot's areas are refused already), two
answers or statements alike as a learner reads them, without tags or entities and in any case
(Multiple Choice, a Single Choice Set question, a Summary set), a text with no gap (Fill in the
Blanks, Drag the Words, Mark the Words), and a picture with no alt text where its field is
optional (`ALT_TEXTS`, held to the pack's fields by `build.test.ts`; H5P.Image's is required).
Each says what to write. `lib/mistakes.mjs` runs in `checkContent`, so a build says them and so
does a check of saved content, and every type file's example says none. Of the owner's 88 real
packages, the 79 checked against their own libraries give 36 notes of a picture with no alt
text in 8 packages, and 4 of answers alike in one, a test whose answers all read "Test"; no
question with no answer marked correct, and no text with no gap.
- **The hand-over carries the source and one web address, the build page's plain one** (#190,
#215, the owner's calls). Beside the package, the hand-over gives the source as a file named
after the package with `.source.json`, and one fixed line saying to open that file on the build
Expand Down Expand Up @@ -454,4 +466,5 @@ text to the content check's rules, and `apps/skills` plays every example untrust
Not built: changing a package in place, which a tool beside it does with `checkContent` as its
check (a package is changed by reading it into a source and building that); reading content made
for another version of a library than the pack's; 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.
judgement of whether content is right beyond those notes, which stays the person's, in the
verifier's preview.
3 changes: 2 additions & 1 deletion design/layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ packages/verify/ a package played headless (lib/verify.mjs) and in a brows
(lib/preview.mjs); lib/serve.mjs what both share, which the extension bundles
packages/author/ a playable .h5p from a short source: lib/build.mjs both builds, node.mjs
Node's, generator.mjs content from semantics, check.mjs, outline.mjs,
types.mjs the editor widgets' rules, read.mjs a package back to a source;
types.mjs the editor widgets' rules, mistakes.mjs the notes of what is
almost surely a mistake, read.mjs a package back to a source;
scripts/ the skill's sync and copy
packages/mcp/ the local MCP server: bin/h5p-mcp.mjs the command, lib/server.mjs its four
tools, lib/folders.mjs the folders it may use
Expand Down
10 changes: 6 additions & 4 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -318,8 +318,8 @@ checks every value against its field, as the build does, and takes what H5P save
sub-content metadata, held to what the platforms keep of them, and each part's `subContentId`, which
the core names the part's statements by, so a learner's record stays the part's after an edit; a part
without one, or with another part's, gets a new one. It places what nobody placed and checks what a
content type's editor would, as the build does, and returns the content as checked with `problems`
and `notes`, each `{ path, message }`. Where the content names an older minor of a library than the
content type's editor would, as the build does, notes what is almost surely a mistake, and returns
the content as checked with `problems` and `notes`, each `{ path, message }`. Where the content names an older minor of a library than the
one it is checked against, a field only that minor has is a note: the player upgrades such content as
it plays. Content saved by the platforms can hold what their editor let an author save and the build
does not, such as a required text left empty; a tool that changes one part keeps the problems under
Expand Down Expand Up @@ -375,8 +375,10 @@ the package's main export has them. A tool beside a build in either imports it f

## What it does not do

It checks structure, not pedagogy: whether the answers are right, the questions fair, or the
pictures placed well is for a person to judge, in
It checks structure, not pedagogy. In the content types where it looks for them, it notes what H5P
allows and is almost surely a mistake: no answer marked correct, two answers or statements alike, a
text with no gap, an optional alt text left blank beside a picture. Whether
the answers are right, the questions fair, or the pictures placed well is for a person to judge, in
[h5p-verify](https://www.npmjs.com/package/@missing-elements/h5p-verify)'s `--preview`. It changes an
existing package only by way of its source, read and built again; `checkContent` is the check for a
tool that changes one in place. The licence of each library is in the pack's `libraries.txt`.
Expand Down
7 changes: 5 additions & 2 deletions packages/author/lib/check.mjs
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
import { ContentGenerator, libraryString } from './generator.mjs'
import { noteMistakes } from './mistakes.mjs'
import { LAYOUTS, placesOf } from './types.mjs'

/**
* Content checked in the form H5P stores it, as the build checks what it writes: every value
* against its field in the libraries' semantics, the hidden fields the editor's widgets set, and
* what those widgets would not let an author save. A tool that changes a saved package runs it on
* against its field in the libraries' semantics, the hidden fields the editor's widgets set, what
* those widgets would not let an author save, and, as notes, what is almost surely a mistake. A tool that changes a saved package runs it on
* what it is about to write, and the build runs it last, on what it is about to write, so that the
* two hold content to one set of rules. No Node import of its own: the libraries are handed in.
*/
Expand Down Expand Up @@ -90,6 +91,8 @@ export function checkContent(libraries, { type, params }) {
const layout = layoutContext(entries, report, note)
const places = placesOf(main.library.machineName, content)
for (const place of places) LAYOUTS[place.library]?.after?.(place.params, place.path, layout(place.library))
// What builds and is almost surely a mistake, which H5P allows: a note, never a problem (#241).
for (const place of places) noteMistakes(place.library, place.params, place.path, note)
for (const place of places) {
if (place.holder && isObject(place.holder.metadata) && place.holder.metadata.title === undefined) place.holder.metadata.title = place.holder.metadata.contentType
}
Expand Down
141 changes: 141 additions & 0 deletions packages/author/lib/mistakes.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
import { decodeEntities, stripTags } from './text.mjs'
import { blanksGaps } from './types.mjs'

/**
* What builds and is almost surely a mistake (#241, item 4 of #219): no answer marked correct, two
* answers alike, a text with no gap, a picture with no alt text where its field is optional. H5P
* allows each, so each is a note and not a problem, and nothing about the content is judged: whether
* an answer is right stays the person's. Run by `checkContent` on content as H5P stores it, so a
* build says them, and so does a check of saved content.
*/

/** @typedef {(path: string, message: string) => void} Note */

/** @param {unknown} value @returns {value is Record<string, any>} */
const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)

/**
* A text as a learner reads it, to compare one with another: no tags or entities, and in one case
* and spacing.
* @param {unknown} value
*/
function plain(value) {
return typeof value === 'string' ? decodeEntities(stripTags(value)).replace(/\s+/g, ' ').trim().toLowerCase() : ''
}

/**
* Each item of a list that reads as an earlier one does.
* @param {unknown} items
* @param {(item: any) => unknown} textOf the text of an item
* @param {string} at the list's path
* @param {string} what what an item is to a learner, as "answer"
* @param {Note} note
*/
function alike(items, textOf, at, what, note) {
if (!Array.isArray(items)) return
/** @type {Map<string, number>} */
const first = new Map()
items.forEach((item, i) => {
const text = plain(textOf(item))
if (!text) return
const earlier = first.get(text)
if (earlier === undefined) first.set(text, i)
else note(`${at}[${i}]`, `reads as ${at.slice(at.lastIndexOf('.') + 1)}[${earlier}] does, so a learner sees the same ${what} twice`)
})
}

/**
* Whether a list marks no item correct, where it has items.
* @param {unknown} items
*/
const noneCorrect = (items) => Array.isArray(items) && items.length > 0 && !items.some((item) => isObject(item) && item.correct === true)

/** A text with no gap, `*word*`, in it, as Drag the Words and Mark the Words find one. @param {unknown} text */
const gapless = (text) => typeof text === 'string' && !/\*[^*]+\*/.test(text)

/**
* Pictures whose alt text is an optional field beside them, by content type: the group that holds
* both, as a path in the type's parameters (`[]` for each item of a list), the picture's field, and
* its alt text's. H5P.Image's alt text is required, so a build refuses one without it already.
* @type {Record<string, [string, string, string][]>}
* @internal
*/
export const ALT_TEXTS = {
'H5P.BranchingScenario': [['branchingScenario.startScreen', 'startScreenImage', 'startScreenAltText']],
'H5P.Dialogcards': [['dialogs[]', 'image', 'imageAltText']],
'H5P.Flashcards': [['cards[]', 'image', 'imageAltText']],
'H5P.ImageHotspots': [['', 'image', 'backgroundImageAltText']],
'H5P.ImagePair': [['cards[]', 'match', 'matchAlt']],
'H5P.MemoryGame': [['cards[]', 'match', 'matchAlt']],
'H5P.QuestionSet': [['introPage', 'backgroundImage', 'backgroundImageAltText']],
'H5P.SpeakTheWordsSet': [['introduction', 'introductionImage', 'introductionImageAltText']]
}

/**
* The groups at a path in parameters, `[]` taking each item of a list, with their paths.
* @param {unknown} value
* @param {string} path
* @param {string} at the value's own path
* @returns {{ group: Record<string, any>, at: string }[]}
*/
function groupsAt(value, path, at) {
if (!isObject(value)) return []
if (!path) return [{ group: value, at }]
const [head, ...rest] = path.split('.')
const name = head.replace(/\[\]$/, '')
const next = value[name]
if (head.endsWith('[]')) return Array.isArray(next) ? next.flatMap((item, i) => groupsAt(item, rest.join('.'), `${at}.${name}[${i}]`)) : []
return groupsAt(next, rest.join('.'), `${at}.${name}`)
}

/**
* The checks of each content type, on its parameters as H5P stores them.
* @type {Record<string, (params: Record<string, any>, path: string, note: Note) => void>}
*/
const CHECKS = {
'H5P.MultiChoice'(params, path, note) {
if (noneCorrect(params.answers)) note(`${path}.answers`, 'marks no answer correct, so no learner can score: set "correct": true on the right one')
alike(params.answers, (answer) => answer?.text, `${path}.answers`, 'answer', note)
},
'H5P.MultiMediaChoice'(params, path, note) {
if (noneCorrect(params.options)) note(`${path}.options`, 'marks no option correct, so no learner can score: set "correct": true on the right one')
},
'H5P.SingleChoiceSet'(params, path, note) {
if (!Array.isArray(params.choices)) return
params.choices.forEach((choice, i) => alike(choice?.answers, (answer) => answer, `${path}.choices[${i}].answers`, 'answer', note))
},
'H5P.Summary'(params, path, note) {
if (!Array.isArray(params.summaries)) return
params.summaries.forEach((set, i) => alike(set?.summary, (statement) => statement, `${path}.summaries[${i}].summary`, 'statement', note))
},
'H5P.Blanks'(params, path, note) {
const texts = Array.isArray(params.questions) ? params.questions.filter((text) => typeof text === 'string') : []
if (texts.length && texts.every((text) => !blanksGaps(text).length)) note(`${path}.questions`, 'has no gap, so a learner has nothing to fill in: put each answer between asterisks, as *Paris*')
},
'H5P.DragText'(params, path, note) {
if (gapless(params.textField)) note(`${path}.textField`, 'has no gap, so a learner has no word to drag: put each word between asterisks, as *Paris*')
},
'H5P.MarkTheWords'(params, path, note) {
if (gapless(params.textField)) note(`${path}.textField`, 'marks no word, so a learner has none to find: put each word to find between asterisks, as *Paris*')
}
}

/**
* What a content type's parameters hold that builds and is almost surely a mistake, noted.
* @param {string} library its machine name
* @param {unknown} params as H5P stores them
* @param {string} path theirs
* @param {Note} note
* @internal
*/
export function noteMistakes(library, params, path, note) {
if (!isObject(params)) return
CHECKS[library]?.(params, path, note)
for (const [group, picture, alt] of ALT_TEXTS[library] ?? []) {
for (const { group: values, at } of groupsAt(params, group, path)) {
const file = values[picture]
if (!isObject(file) || typeof file.path !== 'string' || !file.path.trim() || plain(values[alt])) continue
note(`${at}.${alt}`, `is not written, so a screen reader has nothing to say of the picture in ${picture}: write what it shows`)
}
}
}
2 changes: 1 addition & 1 deletion packages/author/lib/types.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -713,7 +713,7 @@ const imageHotspotQuestion = {
* @param {string} question
* @returns {{ raw: string, content: string }[]} each gap as written, asterisks included, and what the library reads of it
*/
function blanksGaps(question) {
export function blanksGaps(question) {
const gaps = []
let start = question.indexOf('*')
while (start !== -1) {
Expand Down
Loading