Implemented in packages.json
| Task | Command | Output or effect |
|---|---|---|
| Build functional pages | npm run docs:functional | Writes the public pages under docs/ plus docs.html. |
| Capture guide screenshots | npm run docs:screenshots -- --locale en,it | Overwrites stable PNGs, manifest, and index under docs/assets/screenshots/. |
| Build API reference | npm run docs | Writes generated JSDoc under docs/jsdoc/. |
| Clean and rebuild API | npm run docs:rebuild | Deletes only docs/jsdoc/, then regenerates it. |
| Validate all Ghostyles | npm run validate:ghostyles | Reports errors and warnings; stops on the first failed file. |
| Run fast checks | npm run check | Validates Ghostyles, then runs unit tests. |
| Run all tests | npm test | Runs unit tests, then Playwright end-to-end tests. |
| Build architecture map | npm run codemap | Writes the JSON graph and standalone HTML viewer. |
| Extract translations | npm run i18n:extract | Overwrites POT and pipe-delimited summary files. |
Functional HTML and JSDoc are separate outputs.
Edit source
Update docs-src/en/*.body.html for functional pages, JSDOC_index.md for the technical home, or source comments and tutorials for API detail.
Generate
Run npm run docs:functional. Run npm run docs:rebuild when JSDoc inputs changed.
Capture only when needed
Use committed deterministic fixtures. The default screenshot run excludes the optional Face Brush sequence. A Transfer result requires the optional Before, After, and Target trio.
Review evidence
Inspect dimensions, capture region, and provenance in manifest.json. Do not publish synthetic states as observed experiments.
Verify routes and copy
Open the landing page, every changed guide, one JSDoc module, mobile layout, and missing-image behaviour. Extract visible text for editorial review.
Every support script has a boundary.
build-functional-docs.cjs
Wraps English body fragments in shared site chrome and documentation navigation. Writes ten static pages under docs/ and the docs.html compatibility redirect. It does not translate content or generate JSDoc.
capture-doc-screenshots.cjs
Drives Lab and Video Loader with Playwright fixtures. Writes stable screenshots and records pixel dimensions, aspect ratio, crop, viewport, and provenance in the manifest. Brush is an optional path.
build-codemap.js
Parses top-level lab-js/*.js, imports, exports, events, and root HTML entries into codemap/codemap.json. It is a static heuristic, not a runtime trace.
build-codemap-html.js
Injects the JSON map into codemap/codemap-template.html and writes a standalone viewer. Check that the template marker was actually replaced.
validate-plugin.js
Checks one Ghostyle header and supported export patterns without executing the module. Its regular-expression checks cover only a subset of the full authoring policy.
extract-i18n-pot.cjs
Evaluates the translation catalogue and overwrites the POT and summary files. It extracts interface strings, not functional documentation prose.
extract-text-only.js
Extracts reviewable visible copy, metadata, and accessibility attributes from public HTML and structured data. It is an editorial aid, not a complete DOM or localisation audit.
code2prompt.js
Builds filtered source bundles for design, runtime, tests, copy, map, or broad review. Its include and exclude rules are executable configuration; inspect the produced bundle instead of relying only on the estimated tree.
update-coverage-badge.js
Reads Vitest JSON statement coverage and rewrites the marked badge block in README.md. Run coverage first and inspect for an UNKNOWN result.
install-client-interface.cjs
Clears and repopulates the fixed sibling backend client-interface directory. This is the destructive support command: verify the resolved target before running it.
test-upload-consent-post.cjs
Sends an actual multipart clip to the configured backend endpoint and prints response data. It is not a dry run, does not test the browser consent UI, and does not delete the upload.
build-logo.py
Overwrites the named SVG logo set and, when CairoSVG works, PNG icon variants. Reconcile its current geometry and touch-icon output path with the live brand system before regeneration.
Reminder before issuing a new release.
- Run the relevant unit and end-to-end tests, not only
npm run check. - Validate every Ghostyle and inspect warnings.
- Generate functional docs, JSDoc, references, and the codemap when their sources changed.
- Check English copy and translation catalogues separately.
- Open Lab, Loader, Transfer, the docs landing, one guide, and one API page through the same server path used for deployment.
- Inspect the packaged client directory and all “skip missing” messages before deployment.