h5p-type-scaffold

What this skill does

# H5P Content Type Scaffolder

Create a modern H5P content type starting from established boilerplates, with a minimal build pipeline and editor semantics.

## How It Works

1. Choose package intent: `library-install` (default) or `content-import` (advanced).
2. Collect metadata (title, machine name, version, author, license).
3. Generate a boilerplate (default: SNORDIAN) that aligns with current H5P best practices.
4. Provide starter `library.json`, `semantics.json`, and JS/CSS entrypoints.
5. Outline build and packaging steps using `h5p-cli`.

## Concepts

- Content types are runnable libraries under `H5P.*` (`runnable: 1`).
- Editor widgets are non-runnable libraries under `H5PEditor.*` (`runnable: 0`).
- `semantics.json` defines the editor form schema and validation rules.
- Non-runnable dependency libraries (often `H5P.*` or `H5PApi.*`) are used as shared building blocks.

See `references/CONCEPTS.md` for details and official links.

## Packaging Intent (Required)

- `library-install` (default): Upload libraries/content types to platform library installers.
- `content-import` (advanced): Import an authored content instance (`h5p.json` + `content/content.json`) into content import flows.
- This skill scaffolds libraries. It does not generate `content/content.json`.
- Validate unpacked packages before upload:

```bash
bash /mnt/skills/user/h5p-type-scaffold/scripts/validate-package.sh --mode library-install --dir /path/to/unpacked
bash /mnt/skills/user/h5p-type-scaffold/scripts/validate-package.sh --mode content-import --dir /path/to/unpacked
```

## Usage

```bash
bash /mnt/skills/user/h5p-type-scaffold/scripts/scaffold.sh \
  --title "My Content Type" \
  --machine "H5P.MyContentType" \
  --kind "content" \
  --version "1.0.0" \
  --description "Short description" \
  --author "Your Name" \
  --license "MIT" \
  --template "snordian" \
  --out /path/to/output
```

Editor widget example:

```bash
bash /mnt/skills/user/h5p-type-scaffold/scripts/scaffold.sh \
  --title "My Editor Widget" \
  --machine "H5PEditor.MyWidget" \
  --kind "editor" \
  --out /path/to/output
```

## Output

- `library.json` and `semantics.json`
- `src/entries`, `src/scripts`, `src/styles`
- `README.md` (templates)
- `DEV.md` (templates, dev harness)
- Build config and lint config (varies by template)
- Templates live under `assets/templates/`

## Build & Package (h5p-cli)

- Install deps: `npm install`
- Build assets: `npm run build`
- Set up dev environment: `h5p core` then `h5p setup <library>`
- Run local editor/server: `h5p server`
- Pack library for install: `h5p pack <library> [my-library.h5p]` (see `h5p help pack`)
- Install this package in the platform's library/content-type upload flow.
- For library packages, keep `library.json` at the package root and avoid top-level `h5p.json` or `content/`.
- Use `h5p.json` + `content/` only for content-instance export/import flows.
- Run package validation before upload with `scripts/validate-package.sh`.

### Strict-validator packaging (Drupal 11.x H5P 2.0.0+)

Some platforms (notably Drupal 11.x with the H5P 2.0.0 beta module) reject
zip directory entries such as `dist/` or `language/` because they lack an
allowed file extension. Use `scripts/pack.sh` instead of `h5p pack` to produce
a `.h5p` archive that omits directory entries:

```bash
bash /mnt/skills/user/h5p-type-scaffold/scripts/pack.sh \
  --dir /path/to/built-library \
  --out MyLibrary.h5p
```

Add `--strict` to abort if any packaged file lacks an allowed extension.

## Dev Harness (h5p-cli)

- Manual steps: `references/DEV-HARNESS.md`
- Helper script: `scripts/h5p-dev.sh`

## xAPI Integration

- Guidance: `references/XAPI.md` (emit + listen + platform notes)

See `references/H5P-CLI.md` for a fuller command overview and `references/CONTENT-TYPE-AUTHORING.md` for authoring essentials.

## Guidance (2024/2025 Best Practices)

- Default to the SNORDIAN boilerplate for linting, i18n scaffolding, and CI-ready conventions.
- Use the official `h5p/h5p-boilerplate` when you want the simplest baseline.
- Prefer vanilla JS for community maintainability.
- Use `h5p-cli` to pack and manage libraries.
- Validate semantics and editor UX early with a minimal field set.

## Related Community Patterns (Incorporated)

- H5P content is often embedded via iframe in LMS or CMS platforms.
- Common education-focused content types include Interactive Video, Course Presentation, Question Sets, Dialog Cards, and Timeline.
- When embedding, wrap iframes in a responsive container and apply safe, minimal styling.

## Templates

- `snordian` (default): Linting + i18n scaffolding + modern webpack config.
- `vanilla`: Official minimal boilerplate structure.
- `editor`: H5P editor widget boilerplate (`H5PEditor.*`).

## Additional Upstream Options (Not Bundled)

- `h5p/h5p-boilerplate` branches like `question-type` and `question-type-vue` for specialized starting points.
- `otacke/h5p-editor-boilerplate` for building custom H5P editor widgets.
- `NDLA-H5P/generator-h5p-content-type` if you prefer a Yeoman-based generator workflow.
- `tarmoj/h5p-react-boilerplate` for a React-based starter (note: appears stale).

## Troubleshooting

- If machine name is invalid, use `H5P.YourContentType`.
- For editor widgets, use `--kind editor` and a `H5PEditor.YourWidget` machine name.
- If versioning is unclear, start with `1.0.0` and update later.
- If build fails, ensure `node` and `npm` are installed and run `npm install`.
- If import errors mention `content/ not allowed`, missing `preloadDependencies` in `h5p.json`, or invalid `license` in `h5p.json`, you are importing a content package into a library upload flow.
- If Drupal 11.x (H5P 2.0.0 beta) rejects the upload with **"File 'dist/' not allowed"** or **"File 'language/' not allowed"**, the `.h5p` zip contains directory entries. Repack using `scripts/pack.sh --dir <library-dir>` which creates a zip without directory entries.