Contributing and deployment — Avatar Studio Docs

Development checks#

npm run lint
npm run check
npm run test:types
npm run test:mcp
npm audit --prefix mcp --omit=dev
npm run build:pages

For the creator's Chromium browser tests:

npx playwright install chromium
npx playwright test tests/studio.spec.mjs --project=chromium

Set AVATAR_TEST_PORT=4175 if testing the local server on that port. npm test runs the original component's full validation suite, including Chromium, Firefox, and WebKit, and requires those Playwright browsers to be installed. Run npm run test:mcp separately to check the MCP server.

Contributing and security#

See CONTRIBUTING.md for local setup and required checks, SECURITY.md to report vulnerabilities privately, and CODE_OF_CONDUCT.md for community guidelines. CI checks code quality, types, browser compatibility, npm packaging, MCP workflows, dependencies, and GitHub Actions security.

Attribution and license#

Avatar Studio extends Agent Robot Avatar. The original robot character and visual identity were designed by CX ArtLab; this repository adds the personalized creator, accessory catalog, exports, showcases, and local MCP integration.

The original project's character and visual identity notice is retained: the MIT license permits use, modification, and distribution of the software, but does not transfer ownership of the original character's name or identity or grant the right to claim it as another party's original character.

MIT License, with copyright notices for CX ART Lab and ai-calypse.

Website translations#

The header language picker supports English, Spanish, French, German, Portuguese, Japanese, Korean, Simplified Chinese, and Traditional Chinese. Studio copy, accessory options, export feedback, page metadata, tooltips, and accessible labels use local catalogs in demo/avatar-studio-i18n.js. Movement controls and the conversation demo have their own catalogs in demo/agent-robot-avatar-demo-controls.js and demo/agent-robot-avatar-demo-dialog-i18n.js. Brand names, sample people/handles, commands, package names, and file formats stay literal. No visitor text is sent to a translation service.

To add another language, add a complete locale to each catalog and the LANGUAGES list in the demo controls. Use a BCP 47 language tag; configure dir=rtl and review the layout when introducing a right-to-left language. Run npx playwright test tests/translation-coverage.spec.mjs: it checks every offered studio locale against the full phrase catalog and mounted interface, including image descriptions and tooltips. Add new phrases to every locale when changing copy. Missing translations fall back to English at runtime and fail coverage checks. Machine translations should be reviewed by a fluent speaker before release.

Publish to GitHub Pages#

The repository's Deploy Live Demo workflow builds the static site into .pages-site and deploys it with GitHub's Pages actions. It runs for relevant changes on main or manually from Actions. All asset imports are relative so the site works under /avatar-studio/.

In Settings → Pages → Build and deployment, select GitHub Actions as the source.
Merge website changes into main, or run Deploy Live Demo manually on main.
Open https://ai-calypse.github.io/avatar-studio/ after the deployment succeeds.

Run npm run build:pages locally to inspect the generated artifact. The hosted site is a browser-only avatar editor; the MCP server runs locally and is not exposed by Pages.

Website documentation#

The site documentation lives at /docs/. Run npm run build:docs to generate eight navigable pages from this README, mcp/README.md, and mcp/SECURITY.md; npm run dev builds them automatically. The Pages build includes the docs and their visual assets. Edit the Markdown sources and rebuild rather than editing generated HTML. Layout and search are maintained in docs/docs.css and docs/docs.js. Documentation is maintained in English. The header language menu offers opt-in full-page Google Translate translations, with twelve language shortcuts and access to more languages. Code blocks and inline identifiers are marked translate="no". Translation opens in an external service; original English guides and local search remain available. Text embedded in example images stays as drawn. The creator remains available in nine languages through local catalogs.

The creator’s In use section includes all 48 README use cases, loaded from the same manifest, with translated captions, category filters, and search. Its four live previews continue to show your current avatar design.