From 7eecb0b104e4625719f996b4460a4cb2cf6502cd Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Wed, 18 Nov 2026 10:34:25 +0200 Subject: [PATCH 1/3] feat(author): declare a source's own fields once, as a schema (#230) sourceSchema, in zod/mini, is a source's own fields: sourceOf holds each field to it and says its message where the field was written, the Source type is its output, and it is exported, so that a model can be shown the shape of a source before writing one. What one field cannot say alone stays in sourceOf: a content type named loosely, a licence written with its version, a version for a licence that takes none, and fields in the wrong place. The messages are as they were, but every problem of an author is now said at once, and an author written as a name alone is said with the object to write, as Haiku wrote one through the MCP server. zod/mini adds 23 kB minified to a build in a page, where zod's chained API would add 93 kB. --- design/author.md | 8 +++ packages/author/README.md | 7 +- packages/author/lib/build.mjs | 60 ++++++---------- packages/author/lib/core.mjs | 6 +- packages/author/lib/source-schema.mjs | 94 ++++++++++++++++++++++++++ packages/author/package.json | 3 +- packages/author/tests/build.test.ts | 22 +++++- packages/author/tests/package-types.ts | 5 +- pnpm-lock.yaml | 27 +++----- 9 files changed, 167 insertions(+), 65 deletions(-) create mode 100644 packages/author/lib/source-schema.mjs diff --git a/design/author.md b/design/author.md index a112979..831ebf4 100644 --- a/design/author.md +++ b/design/author.md @@ -305,6 +305,14 @@ text to the content check's rules, and `apps/skills` plays every example untrust of the library is the sub-content's `metadata.title`. `readSource` keeps its contract. `sourceType(source, names)` is exported (#176) so the build page hands back the type the build took and keeps no copy of the rule. +- **A source's own fields are declared once, as `sourceSchema`** (#230). `sourceOf` holds each + field to it and says its message where the field was written, it is the `Source` type, and it is + exported so that a model can be shown the shape before writing a source. What one field cannot + say alone stays in `sourceOf`: the content type named loosely, a licence written with its + version, a version for a licence that takes none, and fields in the wrong place. Every problem + of an author is said at once, and an author written as a name alone is said with the object to + write. It is zod/mini, 23 kB minified, since a build runs in a page too, where zod's chained API + takes 93 kB; JSON Schema is made where it is shown. - **The skill is installed, and its page lists what step 3 fetches.** Claude and ChatGPT install the skill as a zip, and Grok reads the zip attached to a message; reading it by its link was dropped (missing-elements.github.io#42). Since the 0.10.0 pin the organisation's site serves the diff --git a/packages/author/README.md b/packages/author/README.md index b62a17c..873238e 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -222,7 +222,12 @@ of the machine names given: its `type`, as it is or loosely (`"interactive-book" none the one name under `contentType` or `library`; `null` where none can be meant, and for a quiz in the published format (`{ "kind": … }`), which the build reads as a Question Set or a Multiple Choice by rules of its own. A page that hands a chat a type's notes with a source's problems asks -it, and hands over the type the build took. `ContentGenerator` is the engine underneath, also run by +it, and hands over the type the build took. `sourceSchema` is a source's own fields, `type`, +`title`, `language`, `license`, `authors` and the rest, as the zod/mini schema a build holds them to; +`toJSONSchema(sourceSchema, { io: 'input' })` from `zod/mini` gives them as JSON Schema, to show a +model the shape of a source before it writes one. A build reads a source more loosely than the +schema, and says what to write: check one with `buildPackage(source, undefined, { check: true })`, +not with the schema alone. `ContentGenerator` is the engine underneath, also run by the repository's sweep of every content type. A tool beside the build takes the libraries as the build loads them, the generator, and the diff --git a/packages/author/lib/build.mjs b/packages/author/lib/build.mjs index 07d7fbc..e40ef90 100644 --- a/packages/author/lib/build.mjs +++ b/packages/author/lib/build.mjs @@ -4,11 +4,12 @@ import { checkContent, layoutContext, valueAt } from './check.mjs' import { ContentGenerator, libraryString } from './generator.mjs' import { installClosure } from './install.mjs' import { loadLibraries } from './libraries.mjs' -import { CC_VERSIONS, LICENSES, ROLES } from './metadata.mjs' +import { CC_VERSIONS } from './metadata.mjs' import { machineNameOf, NAMING_KEYS, namingKey, nearestNames } from './names.mjs' import { quizProblems, quizSource } from './quiz.mjs' import { outlineOf } from './outline.mjs' import { SourceError } from './source-error.mjs' +import { authorHolds, holds, sourceSchema, TYPE } from './source-schema.mjs' import { escapeText } from './text.mjs' import { LAYOUTS, placesOf, videoTimes } from './types.mjs' @@ -24,11 +25,9 @@ export { SourceError } */ /** - * @typedef {{ name: string, role: string }} Author - * @typedef {{ - * type: string, title: string, language: string, license: string, licenseVersion?: string, - * authors: Author[], source?: string, yearFrom?: number, yearTo?: number, params: Record - * }} Source a package's source: the content type, its metadata, and the parameters that differ from the defaults + * @typedef {import('zod/mini').output} Source a package's source, as `sourceSchema` + * declares it: the content type, its metadata, and the parameters that differ from the defaults + * @typedef {Source['authors'][number]} Author * @typedef {{ path: string, message: string }} Problem * @typedef {import('./translate.mjs').TranslationReport} TranslationReport */ @@ -121,10 +120,12 @@ export function sourceOf(input, names) { given.params = Object.fromEntries(rest.map((key) => [key, input[key]])) } else for (const key of rest) report(key, `is not a field of a source; ${fields}`) + // Each field held to `sourceSchema`, with what it cannot say alone written here. + const field = sourceSchema.shape let typed = false const type = typeof given.type === 'string' ? given.type.trim() : '' if (named) typed = true - else if (!type) report(at.type, 'expected a content type\'s machine name, such as "H5P.Blanks"') + else if (!type) holds(field.type, given.type, at.type, report) else if (names) { const found = machineNameOf(type, names) if (!found) { @@ -142,57 +143,36 @@ export function sourceOf(input, names) { report(at.type, `takes the machine name alone, "${name}": the version is the pack's newest`) given.type = name typed = true - } else if (!/^\S+$/.test(type)) report(at.type, 'expected a content type\'s machine name, such as "H5P.Blanks"') + } else if (!/^\S+$/.test(type)) report(at.type, TYPE) else typed = true - /** @type {Record} */ + /** @type {Record} a stand-in for each field that does not hold */ const source = { type: typed ? String(given.type).trim() : '', title: '', language: 'en', license: 'U', authors: [], params: {} } - if (typeof given.title !== 'string' || !given.title.trim()) report(at.title, 'expected the activity\'s title') - else if (given.title.length > 255) report(at.title, 'takes at most 255 characters') - else source.title = given.title - let tag = typeof given.language === 'string' - try { - if (tag) Intl.getCanonicalLocales(given.language) - } catch { - tag = false - } - if (tag) source.language = given.language - else report(at.language, 'expected a BCP 47 language tag, such as "en" or "de-AT"') + if (holds(field.title, given.title, at.title, report)) source.title = given.title + if (holds(field.language, given.language, at.language, report)) source.language = given.language // A licence written with its version, "CC BY 4.0", as it is spoken of: H5P keeps the version in // a field of its own. The names alone, which this problem used to list, had a chat drop the // version to fit them. const versioned = typeof given.license === 'string' ? /^CC[ -](BY(?:-(?:NC-SA|NC-ND|NC|ND|SA))?)[ -]v?(\d\.\d)$/i.exec(given.license.trim()) : null const license = versioned ? `CC ${versioned[1].toUpperCase()}` : given.license - if (LICENSES.includes(given.license)) source.license = given.license - else if (versioned) { + if (versioned) { const written = JSON.stringify(given.license) if (given.licenseVersion !== undefined) report(at.license, `${written} holds the version too, which licenseVersion names: write "license": "${license}"`) else if (CC_VERSIONS.includes(versioned[2])) report(at.license, `${written} holds the version too: write "license": "${license}" and "licenseVersion": "${versioned[2]}"`) else report(at.license, `${written} holds a version too: write "license": "${license}" and "licenseVersion", one of ${CC_VERSIONS.join(', ')}`) source.license = license if (given.licenseVersion === undefined && CC_VERSIONS.includes(versioned[2])) source.licenseVersion = versioned[2] - } else report(at.license, `use one of ${LICENSES.map((each) => JSON.stringify(each)).join(', ')}; "U" when it is not known`) + } else if (holds(field.license, given.license, at.license, report)) source.license = given.license if (given.licenseVersion !== undefined) { if (!String(license).startsWith('CC ') || license === 'CC0 1.0' || license === 'CC PDM') report(at.licenseVersion, 'is for a Creative Commons BY licence only') - else if (!CC_VERSIONS.includes(given.licenseVersion)) report(at.licenseVersion, `use one of ${CC_VERSIONS.join(', ')}`) - else source.licenseVersion = given.licenseVersion + else if (holds(field.licenseVersion, given.licenseVersion, at.licenseVersion, report)) source.licenseVersion = given.licenseVersion } - if (!Array.isArray(given.authors) || !given.authors.length) report(at.authors, 'name at least one author: [{ "name": "…", "role": "Author" }]') - else given.authors.forEach((/** @type {unknown} */ author, /** @type {number} */ i) => { - const before = problems.length - if (!isObject(author) || typeof author.name !== 'string' || !author.name.trim()) report(`${at.authors}[${i}].name`, 'expected the author\'s name') - else if (!ROLES.includes(author.role)) report(`${at.authors}[${i}].role`, `use one of ${ROLES.join(', ')}`) - else for (const key of Object.keys(author)) if (key !== 'name' && key !== 'role') report(`${at.authors}[${i}].${key}`, 'is not part of an author; write name and role') - if (problems.length === before) source.authors.push(author) - }) - if (given.source !== undefined && (typeof given.source !== 'string' || !/^https?:\/\/\S+$/i.test(given.source))) report(at.source, 'expected the address the content comes from') - else if (given.source !== undefined) source.source = given.source - for (const key of ['yearFrom', 'yearTo']) { - if (given[key] !== undefined && !Number.isInteger(given[key])) report(at[key], 'expected a year') - else if (given[key] !== undefined) source[key] = given[key] + // The authors that hold are kept, so the content is checked with them. + const authorsHold = holds(field.authors, given.authors, at.authors, report) + if (Array.isArray(given.authors)) source.authors = authorsHold ? given.authors : given.authors.filter(authorHolds) + for (const key of /** @type {const} */ (['source', 'yearFrom', 'yearTo', 'params'])) { + if (given[key] !== undefined && holds(field[key], given[key], at[key], report)) source[key] = given[key] } - if (given.params !== undefined && !isObject(given.params)) report('params', 'expected an object of the content type\'s fields') - else if (given.params !== undefined) source.params = given.params return { source: /** @type {Source} */ (source), problems, typed } } diff --git a/packages/author/lib/core.mjs b/packages/author/lib/core.mjs index b43de7a..04fb386 100644 --- a/packages/author/lib/core.mjs +++ b/packages/author/lib/core.mjs @@ -2,8 +2,9 @@ * @missing-elements/h5p-author/core: what the package does that needs neither Node nor a page, for * a tool that runs beside a build in either: the generator, the libraries loaded as a build loads * them from any source of them, the parts a content type's build can read, the check of saved - * content, the rules for text, and which content type a source is written in, as a build reads it. The package's entry for Node (`.`) and the one for a page - * (`./browser`) carry all of it, each with its own `buildPackage` and `openPack`. + * content, the rules for text, which content type a source is written in, as a build reads it, and + * a source's own fields as the schema a build holds them to. The package's entry for Node (`.`) and + * the one for a page (`./browser`) carry all of it, each with its own `buildPackage` and `openPack`. */ export { bundleLibraries, contentTypes } from './bundle.mjs' @@ -15,6 +16,7 @@ export { loadLibraries, packageLibraries } from './libraries.mjs' export { sourceType } from './names.mjs' export { GENERATED_END, GENERATED_START } from './schema.mjs' export { SourceError } from './source-error.mjs' +export { sourceSchema } from './source-schema.mjs' export { allowedTags, editorWidget, markupText, plainText, takesMarkup } from './text.mjs' /** diff --git a/packages/author/lib/source-schema.mjs b/packages/author/lib/source-schema.mjs new file mode 100644 index 0000000..edea28f --- /dev/null +++ b/packages/author/lib/source-schema.mjs @@ -0,0 +1,94 @@ +/** + * A source's own fields, declared once: the outer shape of what a build takes. `sourceOf` holds + * each field to it and says its message where the field was written, it is the `Source` type, and + * an app is shown it as the shape of a source before one is written (#230). + * + * In zod/mini, since a build runs in a page too, where zod's chained API weighs four times as + * much. Its messages are the build's problems, each with what to write. + */ +import * as z from 'zod/mini' +import { CC_VERSIONS, LICENSES, ROLES } from './metadata.mjs' + +/** @internal */ +export const TYPE = 'expected a content type\'s machine name, such as "H5P.Blanks"' +const TITLE = 'expected the activity\'s title' +const LANGUAGE = 'expected a BCP 47 language tag, such as "en" or "de-AT"' +const NAME = 'expected the author\'s name' +const AUTHORS = 'name at least one author: [{ "name": "…", "role": "Author" }]' +const ADDRESS = 'expected the address the content comes from' +const YEAR = 'expected a year' + +/** @param {string} text */ +const written = (text) => text.trim() !== '' + +/** @param {string} tag */ +const isTag = (tag) => { + try { + Intl.getCanonicalLocales(tag) + return true + } catch { + return false + } +} + +/** An author, in a role H5P names. One written as a name alone, as a chat writes one, is said with the object to write. */ +const author = z.strictObject({ + name: z.string({ error: NAME }).check(z.refine(written, { error: NAME })), + role: z.enum(ROLES, { error: `use one of ${ROLES.join(', ')}` }) +}, { + error: (issue) => { + if (issue.code === 'unrecognized_keys') return 'is not part of an author; write name and role' + return typeof issue.input === 'string' + ? `expected an author: write { "name": ${JSON.stringify(issue.input)}, "role": "Author" }` + : 'expected an author, { "name": "…", "role": "Author" }' + } +}) + +/** + * What a source says of itself, and its content's fields in `params`. What a field cannot say + * alone stays in `sourceOf`: a content type named loosely, a licence written with its version, a + * version for a licence that takes none, and fields written in the wrong place. + */ +export const sourceSchema = z.object({ + type: z.string({ error: TYPE }).check(z.refine(written, { error: TYPE }), z.describe('The content type\'s machine name, as "H5P.MultiChoice"')), + title: z.string({ error: TITLE }).check(z.refine(written, { error: TITLE }), z.maxLength(255, { error: 'takes at most 255 characters' })), + language: z.string({ error: LANGUAGE }).check(z.refine(isTag, { error: LANGUAGE }), z.describe('A BCP 47 tag, as "en"')), + license: z.enum(LICENSES, { error: `use one of ${LICENSES.map((each) => JSON.stringify(each)).join(', ')}; "U" when it is not known` }), + licenseVersion: z.optional(z.enum(CC_VERSIONS, { error: `use one of ${CC_VERSIONS.join(', ')}` }).check(z.describe('For a CC BY licence only'))), + authors: z.array(author, { error: AUTHORS }).check(z.minLength(1, { error: AUTHORS })), + source: z.optional(z.string({ error: ADDRESS }).check(z.regex(/^https?:\/\/\S+$/i, { error: ADDRESS }))), + yearFrom: z.optional(z.int({ error: YEAR })), + yearTo: z.optional(z.int({ error: YEAR })), + params: z._default(z.record(z.string(), z.unknown(), { error: 'expected an object of the content type\'s fields' }), {}) + .check(z.describe('The content\'s fields that differ from their defaults')) +}) + +/** + * Holds a value written for one of `sourceSchema`'s fields to it, and says each problem at the path + * it was written at, one a path, as a build says one thing of a field. + * @param {z.ZodMiniType} schema one of `sourceSchema.shape` + * @param {unknown} value as written + * @param {string} path where it was written + * @param {(path: string, message: string) => void} report + * @returns {boolean} whether it holds + * @internal + */ +export function holds(schema, value, path, report) { + const result = schema.safeParse(value) + if (result.success) return true + const said = new Set() + for (const issue of result.error.issues) { + // Keys that are no part of an object are one issue: a problem each, at its own path. + const places = issue.code === 'unrecognized_keys' ? issue.keys.map((key) => [...issue.path, key]) : [issue.path] + for (const place of places) { + const at = path + place.map((key) => (typeof key === 'number' ? `[${key}]` : `.${String(key)}`)).join('') + if (said.has(at)) continue + said.add(at) + report(at, issue.message) + } + } + return false +} + +/** @internal An author as `sourceSchema` takes one, for keeping those that are right. */ +export const authorHolds = (/** @type {unknown} */ value) => author.safeParse(value).success diff --git a/packages/author/package.json b/packages/author/package.json index 276fda7..5346866 100644 --- a/packages/author/package.json +++ b/packages/author/package.json @@ -68,7 +68,8 @@ "@missing-elements/h5p-libraries": "workspace:*", "@missing-elements/h5p-normalize": "workspace:^", "@missing-elements/h5p-offline-player": "workspace:*", - "@zip.js/zip.js": "^2.24.0" + "@zip.js/zip.js": "^2.24.0", + "zod": "^4.6.7" }, "devDependencies": { "@missing-elements/h5p-verify": "workspace:*", diff --git a/packages/author/tests/build.test.ts b/packages/author/tests/build.test.ts index 70d900d..967fe60 100644 --- a/packages/author/tests/build.test.ts +++ b/packages/author/tests/build.test.ts @@ -9,8 +9,10 @@ import { promisify } from 'node:util' import { BlobReader, TextWriter, Uint8ArrayWriter, ZipReader } from '@zip.js/zip.js' import { pack } from '@missing-elements/h5p-libraries' import { afterAll, beforeAll, describe, expect, it } from 'vitest' -import { buildPackage, librariesIn, missingForInstall, SourceError } from '../lib/author.mjs' +import { toJSONSchema } from 'zod/mini' +import { buildPackage, librariesIn, missingForInstall, SourceError, sourceSchema } from '../lib/author.mjs' import { readSource } from '../lib/build.mjs' +import { LICENSES } from '../lib/metadata.mjs' import { MediaStore } from '../lib/media.mjs' import { nodeMedia } from '../lib/node.mjs' import { quizProblems } from '../lib/quiz.mjs' @@ -360,6 +362,24 @@ describe('any content type in the pack', () => { expect((await readdir(dir)).filter(name => name.startsWith('failed-') || name.startsWith('.h5p-author-'))).toEqual([]) }) + it('holds a source\'s own fields to one schema, which is what an app is shown of a source (#230)', async () => { + const blanks = { type: 'H5P.Blanks', params: { questions: ['The *Danube* flows east.'] } } + // An author written as a name alone, as Haiku wrote one through the MCP server: said with the object to write. + expect(await problems({ ...META, ...blanks, authors: ['Unknown'] })).toEqual(['authors[0]: expected an author: write { "name": "Unknown", "role": "Author" }']) + // Every problem of an author at once, each at its own path. + expect(await problems({ ...META, ...blanks, authors: [{ name: ' ', role: 'Writer', email: 'ann@example.org' }] })).toEqual([ + 'authors[0].name: expected the author\'s name', + 'authors[0].role: use one of Author, Editor, Licensee, Originator', + 'authors[0].email: is not part of an author; write name and role' + ]) + // The same fields, as JSON Schema: those a source must name, the codes, an author's two fields. + const shape = toJSONSchema(sourceSchema, { io: 'input' }) as { required: string[], properties: Record } + expect(shape.required).toEqual(['type', 'title', 'language', 'license', 'authors']) + expect(shape.properties.license.enum).toEqual(LICENSES) + expect(shape.properties.authors.items).toMatchObject({ required: ['name', 'role'], additionalProperties: false }) + expect(sourceSchema.safeParse({ ...META, ...blanks }).success).toBe(true) + }) + it('says what to write for what is in the wrong place, checks it in the same build, and counts no list it refused an item of (#172)', async () => { // A book's chapters as a chat without the type's file writes them: pages of their own, with no // H5P.Column around them, and sub-content in the place of a page's items. Every one of it in diff --git a/packages/author/tests/package-types.ts b/packages/author/tests/package-types.ts index cd58e34..0ee4a35 100644 --- a/packages/author/tests/package-types.ts +++ b/packages/author/tests/package-types.ts @@ -2,7 +2,7 @@ // published declarations, not the source. `pnpm typecheck` writes them first. import { allowedTags, buildPackage, bundleLibraries, checkContent, ContentGenerator, contentTypes, GENERATED_START, loadLibraries, markupText, openPack, packageLibraries, plainText, schemaOf, SourceError, - writeBundle, writeBundles, + sourceSchema, writeBundle, writeBundles, type BuildResult, type BundleResult, type CheckedContent, type LibraryRecord, type LibrarySource, type PackageFiles, type Source, type TranslationReport } from '@missing-elements/h5p-author' // @ts-expect-error The source reader is internal: a helper the tests import from its module. @@ -13,6 +13,9 @@ import { bundleLibraries as bundleBeside, checkContent as checkBeside, ContentGe import { buildPackage as noBuild } from '@missing-elements/h5p-author/core' const source: Source = { type: 'H5P.TrueFalse', title: 'T', language: 'en', license: 'U', authors: [{ name: 'A', role: 'Author' }], params: {} } +// The schema a source's own fields are held to is the `Source` type. +const parsed: Source | undefined = sourceSchema.safeParse({ ...source, params: undefined }).data +void parsed export async function check(): Promise<[BuildResult, string, string]> { const built = await buildPackage(source, 'out.h5p', { libraries: 'parts', base: '.' }) try { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ba21d29..d16385c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -102,6 +102,9 @@ importers: '@zip.js/zip.js': specifier: ^2.24.0 version: 2.24.0 + zod: + specifier: ^4.6.7 + version: 4.6.7 devDependencies: '@missing-elements/h5p-verify': specifier: workspace:* @@ -708,35 +711,30 @@ packages: engines: {node: '>= 10'} cpu: [arm64] os: [linux] - libc: [glibc] '@napi-rs/keyring-linux-arm64-musl@1.3.0': resolution: {integrity: sha512-iIK6JWHXAJqDrEyLY3TmswwloVyt2vj+04TZnew+uSJ9gnDO8EwRbp3/iw3LpWaXiDO7VomGO6y8I0Id8uBZSw==} engines: {node: '>= 10'} cpu: [arm64] os: [linux] - libc: [musl] '@napi-rs/keyring-linux-riscv64-gnu@1.3.0': resolution: {integrity: sha512-/PGqrwn6EwgtK6vccASSXJRfOSP4vN1F4ASsIQ+7MdrK6hNvAJ1FZPrIuD5gGGdxezo3F++To2Wq7DbuGIeuNQ==} engines: {node: '>= 10'} cpu: [riscv64] os: [linux] - libc: [glibc] '@napi-rs/keyring-linux-x64-gnu@1.3.0': resolution: {integrity: sha512-2PDK1WKWTu9lBGq9VvNEkSlQD3O7YwVpmnyN2M3cy4v7NJ/8gDMd9GXv3G+FVXN13uhp4gnnPBS+ScefmEeD2A==} engines: {node: '>= 10'} cpu: [x64] os: [linux] - libc: [glibc] '@napi-rs/keyring-linux-x64-musl@1.3.0': resolution: {integrity: sha512-oJ2HkX8YUo46QBkn0pG+HuIKQNqr523q6vBobCn+P95s4C4K6/kLBqHY/1bg5J4ap31DzsznhnFKcfBNBsjCnw==} engines: {node: '>= 10'} cpu: [x64] os: [linux] - libc: [musl] '@napi-rs/keyring-win32-arm64-msvc@1.3.0': resolution: {integrity: sha512-tOd3c/uAaeoE4ycVlmAdSvygz0Zt3zdca6Y7gokBeIbaRDWpjDIUOpU3MvML59XAaqyuKGsVVu0F/DZb1lHPmw==} @@ -801,28 +799,24 @@ packages: engines: {node: '>= 10'} cpu: [arm64] os: [linux] - libc: [glibc] '@node-rs/crc32-linux-arm64-musl@1.10.8': resolution: {integrity: sha512-eS8YXANJLBqdOzf5jCNVEXiDI4wjXVqQybaJextJJINvHhnhhOXPar8402GMagewOxGxYsy4C69G8rBIzqL4cg==} engines: {node: '>= 10'} cpu: [arm64] os: [linux] - libc: [musl] '@node-rs/crc32-linux-x64-gnu@1.10.8': resolution: {integrity: sha512-DFd0eV47MAykz4PQDcBSlEvY3CtXqPt2gkBpvPngCpOUoIJgEk9tKtPjEgUwLatMkvsy4fEvAg7gckGickOyEw==} engines: {node: '>= 10'} cpu: [x64] os: [linux] - libc: [glibc] '@node-rs/crc32-linux-x64-musl@1.10.8': resolution: {integrity: sha512-U7fP8FjDQuOb61YoT8EoWDIJ9x40ZrCzM6OcAH1wqYiu9Z94U14S+i8KwTC7YorotGtICdYZ/APn1eI8vNne5w==} engines: {node: '>= 10'} cpu: [x64] os: [linux] - libc: [musl] '@node-rs/crc32-win32-arm64-msvc@1.10.8': resolution: {integrity: sha512-VJezyT9OWnMPnArDR5ok0ARLemiL83LLNYh4MC++oHoLegqzyBllqNlO8fVp2PmczGkn+rfKkZbtG4w3MQ6BbQ==} @@ -893,42 +887,36 @@ packages: engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [linux] - libc: [glibc] '@rolldown/binding-linux-arm64-musl@1.2.16': resolution: {integrity: sha512-hrJpblMsrQ58U9veWpbXzkhV5zStunds6HWLprqq1qauvgBr1E6P+24kLj6lSLI9vjRn/RYpjprhkHQPKGWpNg==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [linux] - libc: [musl] '@rolldown/binding-linux-ppc64-gnu@1.2.16': resolution: {integrity: sha512-qJd/dC6j6CwLG9/s/RP2nb1RZ0GIgj7Ioj7x/SYa3RzjVrlzrmH0fhIOpfvqQDeIsdP0loi+kHaMhJzY1PBIaA==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [ppc64] os: [linux] - libc: [glibc] '@rolldown/binding-linux-s390x-gnu@1.2.16': resolution: {integrity: sha512-Vx7Xg5uUJuNcujJjI70OICaH0EYj80BtOLZTSN7uOYg8QOLlyKnaG0IW7Fn/J0IpJsaKzmDKMhOQv1JBM9m9vg==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [s390x] os: [linux] - libc: [glibc] '@rolldown/binding-linux-x64-gnu@1.2.16': resolution: {integrity: sha512-TNKhgE3uJTsTzatUSSYt0Kgo+Oa2uSlSjz4r1aEIea7HX6ULBym4fAlYUhG1i6pjNf2njfCUAfKwr6C3E9Xg1w==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [linux] - libc: [glibc] '@rolldown/binding-linux-x64-musl@1.2.16': resolution: {integrity: sha512-7chXdpjXZ8qG0+mIxECN3cT9kvhZ3/oZhMX6Pp876P7CDrIy8nJswva6Mq357JR7eYXfuskwZxMeV1SzoZdHrA==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [linux] - libc: [musl] '@rolldown/binding-openharmony-arm64@1.2.16': resolution: {integrity: sha512-Kwjt+7uNTJK5/MDkGWGVO2KQPnj8yAV75dMpfwyHZrJSXWHrniOB0aUEWlVYf3H1hOqFLIStLdM5QXq6bnKmOQ==} @@ -1688,28 +1676,24 @@ packages: engines: {node: '>= 12.0.0'} cpu: [arm64] os: [linux] - libc: [glibc] lightningcss-linux-arm64-musl@1.33.0: resolution: {integrity: sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ==} engines: {node: '>= 12.0.0'} cpu: [arm64] os: [linux] - libc: [musl] lightningcss-linux-x64-gnu@1.33.0: resolution: {integrity: sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg==} engines: {node: '>= 12.0.0'} cpu: [x64] os: [linux] - libc: [glibc] lightningcss-linux-x64-musl@1.33.0: resolution: {integrity: sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw==} engines: {node: '>= 12.0.0'} cpu: [x64] os: [linux] - libc: [musl] lightningcss-win32-arm64-msvc@1.33.0: resolution: {integrity: sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA==} @@ -2253,6 +2237,9 @@ packages: resolution: {integrity: sha512-U/PBtDf35ff0D8X8D0jfdzHYEPFxAI7jJlxZXwCSez5M3190m+QobIfh+sWDWSHMCWWJN2AWamkegn6vr6YBTw==} engines: {node: '>=18'} + zod@4.6.7: + resolution: {integrity: sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==} + zwitch@2.0.4: resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==} @@ -3950,4 +3937,6 @@ snapshots: yoctocolors-cjs@2.1.3: {} + zod@4.6.7: {} + zwitch@2.0.4: {} From a817aa23c0102d9b7b94ab9d39c21ae4e40f6e42 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Wed, 18 Nov 2026 10:40:05 +0200 Subject: [PATCH 2/3] fix(author): show params with no default, as Haiku built a video from an empty one (#230) A schema shown with "params": { "default": {} } had Haiku send an empty params three times in one Interactive Video run, though a build refused each. params is optional, as a build takes it, with no default said, and the Source type has it optional too. --- packages/author/lib/source-schema.mjs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/author/lib/source-schema.mjs b/packages/author/lib/source-schema.mjs index edea28f..c82ac2b 100644 --- a/packages/author/lib/source-schema.mjs +++ b/packages/author/lib/source-schema.mjs @@ -59,8 +59,8 @@ export const sourceSchema = z.object({ source: z.optional(z.string({ error: ADDRESS }).check(z.regex(/^https?:\/\/\S+$/i, { error: ADDRESS }))), yearFrom: z.optional(z.int({ error: YEAR })), yearTo: z.optional(z.int({ error: YEAR })), - params: z._default(z.record(z.string(), z.unknown(), { error: 'expected an object of the content type\'s fields' }), {}) - .check(z.describe('The content\'s fields that differ from their defaults')) + params: z.optional(z.record(z.string(), z.unknown(), { error: 'expected an object of the content type\'s fields' }) + .check(z.describe('The content type\'s fields that differ from their defaults'))) }) /** From f64fda4bc8f0a7a7a83f51145d1d8129665c8ac4 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Wed, 18 Nov 2026 11:15:51 +0200 Subject: [PATCH 3/3] fix(author): one list of a source's fields, a strict schema, zod as the caller's own (#230) What cubic found: build.mjs kept its own list of a source's fields beside the schema, so it now takes them from sourceSchema.shape, and the messages for a field no source has and for a source that is no object are said in one place. sourceSchema refuses a field no source has, as a build does, where it dropped one; an app is shown that too. The README says that toJSONSchema comes from a zod of the caller's own, 4.2 or later, since pnpm does not let a package import the author package's copy. --- design/author.md | 17 +++++++++-------- packages/author/README.md | 12 +++++++----- packages/author/lib/build.mjs | 13 ++++++------- packages/author/lib/source-schema.mjs | 23 +++++++++++++++++------ packages/author/tests/build.test.ts | 5 +++++ 5 files changed, 44 insertions(+), 26 deletions(-) diff --git a/design/author.md b/design/author.md index 831ebf4..a1ef636 100644 --- a/design/author.md +++ b/design/author.md @@ -305,14 +305,15 @@ text to the content check's rules, and `apps/skills` plays every example untrust of the library is the sub-content's `metadata.title`. `readSource` keeps its contract. `sourceType(source, names)` is exported (#176) so the build page hands back the type the build took and keeps no copy of the rule. -- **A source's own fields are declared once, as `sourceSchema`** (#230). `sourceOf` holds each - field to it and says its message where the field was written, it is the `Source` type, and it is - exported so that a model can be shown the shape before writing a source. What one field cannot - say alone stays in `sourceOf`: the content type named loosely, a licence written with its - version, a version for a licence that takes none, and fields in the wrong place. Every problem - of an author is said at once, and an author written as a name alone is said with the object to - write. It is zod/mini, 23 kB minified, since a build runs in a page too, where zod's chained API - takes 93 kB; JSON Schema is made where it is shown. +- **A source's own fields are declared once, as `sourceSchema`** (#230). `sourceOf` takes the list + of fields from it, holds each field to it and says its message where the field was written; it is + the `Source` type, it takes no other field, as a build does not, and it is exported so that a + model can be shown the shape before writing a source. What one field cannot say alone stays in + `sourceOf`: the content type named loosely, a licence written with its version, a version for a + licence that takes none, and fields in the wrong place. Every problem of an author is said at + once, and an author written as a name alone is said with the object to write. It is zod/mini, + 23 kB minified, since a build runs in a page too, where zod's chained API takes 93 kB; JSON + Schema is made where it is shown. - **The skill is installed, and its page lists what step 3 fetches.** Claude and ChatGPT install the skill as a zip, and Grok reads the zip attached to a message; reading it by its link was dropped (missing-elements.github.io#42). Since the 0.10.0 pin the organisation's site serves the diff --git a/packages/author/README.md b/packages/author/README.md index 873238e..1b7fef8 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -223,11 +223,13 @@ none the one name under `contentType` or `library`; `null` where none can be mea in the published format (`{ "kind": … }`), which the build reads as a Question Set or a Multiple Choice by rules of its own. A page that hands a chat a type's notes with a source's problems asks it, and hands over the type the build took. `sourceSchema` is a source's own fields, `type`, -`title`, `language`, `license`, `authors` and the rest, as the zod/mini schema a build holds them to; -`toJSONSchema(sourceSchema, { io: 'input' })` from `zod/mini` gives them as JSON Schema, to show a -model the shape of a source before it writes one. A build reads a source more loosely than the -schema, and says what to write: check one with `buildPackage(source, undefined, { check: true })`, -not with the schema alone. `ContentGenerator` is the engine underneath, also run by +`title`, `language`, `license`, `authors` and the rest, as the zod/mini schema a build holds them to, +and no other field. To show a model the shape of a source before it writes one, turn it into JSON +Schema with `toJSONSchema(sourceSchema, { io: 'input' })` from zod 4.2 or later, installed as a +dependency of your own, since the author package's copy is not yours to import. A build reads a +source more loosely than the schema, and says what to write: check one with +`buildPackage(source, undefined, { check: true })`, not with the schema alone. `ContentGenerator` +is the engine underneath, also run by the repository's sweep of every content type. A tool beside the build takes the libraries as the build loads them, the generator, and the diff --git a/packages/author/lib/build.mjs b/packages/author/lib/build.mjs index e40ef90..dc341a4 100644 --- a/packages/author/lib/build.mjs +++ b/packages/author/lib/build.mjs @@ -9,7 +9,7 @@ import { machineNameOf, NAMING_KEYS, namingKey, nearestNames } from './names.mjs import { quizProblems, quizSource } from './quiz.mjs' import { outlineOf } from './outline.mjs' import { SourceError } from './source-error.mjs' -import { authorHolds, holds, sourceSchema, TYPE } from './source-schema.mjs' +import { authorHolds, holds, NO_FIELD, NO_SOURCE, sourceSchema, TYPE } from './source-schema.mjs' import { escapeText } from './text.mjs' import { LAYOUTS, placesOf, videoTimes } from './types.mjs' @@ -35,8 +35,8 @@ export { SourceError } /** @param {unknown} value @returns {value is Record} */ const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) -/** A source's fields. */ -const FIELDS = ['type', 'title', 'language', 'license', 'licenseVersion', 'authors', 'source', 'yearFrom', 'yearTo', 'params'] +/** A source's fields, as `sourceSchema` declares them. */ +const FIELDS = Object.keys(sourceSchema.shape) /** Those a source says of itself, which H5P keeps in an object of their own, `metadata`. */ const OWN = FIELDS.filter((name) => name !== 'type' && name !== 'params') @@ -78,8 +78,7 @@ export function sourceOf(input, names) { /** @type {Problem[]} */ const problems = [] const report = (/** @type {string} */ path, /** @type {string} */ message) => problems.push({ path, message }) - if (!isObject(input)) throw new SourceError([{ path: 'source', message: 'expected an object: { "type", "title", "language", "license", "authors", "params" }' }]) - const fields = `the fields are ${FIELDS.join(', ')}` + if (!isObject(input)) throw new SourceError([{ path: 'source', message: NO_SOURCE }]) /** @type {Record} what is written for each field */ const given = Object.fromEntries(FIELDS.filter((name) => input[name] !== undefined).map((name) => [name, input[name]])) /** @type {Record} where each is written */ @@ -110,7 +109,7 @@ export function sourceOf(input, names) { at[name] = `metadata.${name}` } for (const inner of Object.keys(value)) { - if (!own.includes(inner)) report(`metadata.${inner}`, OWN.includes(inner) ? 'is written beside type already' : `is not a field of a source; ${fields}`) + if (!own.includes(inner)) report(`metadata.${inner}`, OWN.includes(inner) ? 'is written beside type already' : NO_FIELD) } rest = rest.filter((each) => each !== 'metadata') } @@ -118,7 +117,7 @@ export function sourceOf(input, names) { if (rest.length && given.params === undefined) { report('params', `is not written: the content's fields go in it, not beside type: write "params": { ${rest.map((key) => `"${key}": …`).join(', ')} }`) given.params = Object.fromEntries(rest.map((key) => [key, input[key]])) - } else for (const key of rest) report(key, `is not a field of a source; ${fields}`) + } else for (const key of rest) report(key, NO_FIELD) // Each field held to `sourceSchema`, with what it cannot say alone written here. const field = sourceSchema.shape diff --git a/packages/author/lib/source-schema.mjs b/packages/author/lib/source-schema.mjs index c82ac2b..8cd7406 100644 --- a/packages/author/lib/source-schema.mjs +++ b/packages/author/lib/source-schema.mjs @@ -44,12 +44,8 @@ const author = z.strictObject({ } }) -/** - * What a source says of itself, and its content's fields in `params`. What a field cannot say - * alone stays in `sourceOf`: a content type named loosely, a licence written with its version, a - * version for a licence that takes none, and fields written in the wrong place. - */ -export const sourceSchema = z.object({ +/** A source's fields, in the order they are listed, each with what it takes. */ +const fields = { type: z.string({ error: TYPE }).check(z.refine(written, { error: TYPE }), z.describe('The content type\'s machine name, as "H5P.MultiChoice"')), title: z.string({ error: TITLE }).check(z.refine(written, { error: TITLE }), z.maxLength(255, { error: 'takes at most 255 characters' })), language: z.string({ error: LANGUAGE }).check(z.refine(isTag, { error: LANGUAGE }), z.describe('A BCP 47 tag, as "en"')), @@ -61,6 +57,21 @@ export const sourceSchema = z.object({ yearTo: z.optional(z.int({ error: YEAR })), params: z.optional(z.record(z.string(), z.unknown(), { error: 'expected an object of the content type\'s fields' }) .check(z.describe('The content type\'s fields that differ from their defaults'))) +} + +/** @internal What is said of a key that is no field of a source. */ +export const NO_FIELD = `is not a field of a source; the fields are ${Object.keys(fields).join(', ')}` +/** @internal What is said of a source that is no object. */ +export const NO_SOURCE = 'expected an object: { "type", "title", "language", "license", "authors", "params" }' + +/** + * What a source says of itself, and its content's fields in `params`, and nothing else, as a build + * refuses any other field. What a field cannot say alone stays in `sourceOf`: a content type named + * loosely, a licence written with its version, a version for a licence that takes none, and fields + * written in the wrong place. + */ +export const sourceSchema = z.strictObject(fields, { + error: (issue) => (issue.code === 'unrecognized_keys' ? NO_FIELD : NO_SOURCE) }) /** diff --git a/packages/author/tests/build.test.ts b/packages/author/tests/build.test.ts index 967fe60..8c1522f 100644 --- a/packages/author/tests/build.test.ts +++ b/packages/author/tests/build.test.ts @@ -377,7 +377,12 @@ describe('any content type in the pack', () => { expect(shape.required).toEqual(['type', 'title', 'language', 'license', 'authors']) expect(shape.properties.license.enum).toEqual(LICENSES) expect(shape.properties.authors.items).toMatchObject({ required: ['name', 'role'], additionalProperties: false }) + // No other field, as a build refuses one: said as the build says it. + expect(shape).toMatchObject({ additionalProperties: false }) expect(sourceSchema.safeParse({ ...META, ...blanks }).success).toBe(true) + expect(sourceSchema.safeParse({ ...META, ...blanks, extra: 1 }).error?.issues.map(({ message }) => message)).toEqual([ + 'is not a field of a source; the fields are type, title, language, license, licenseVersion, authors, source, yearFrom, yearTo, params' + ]) }) it('says what to write for what is in the wrong place, checks it in the same build, and counts no list it refused an item of (#172)', async () => {