# Contributing to Toddler Playroom

Toddler Playroom welcomes focused improvements to released games and small, complete new games. Contributions may be created with AI, but the contributor remains responsible for the behavior, originality, child safety, licensing, and verification of the result.

## Start with one child job

Write one sentence in this form:

> When a child opens this game, they want to understand and repeat one playful action, so they can independently finish a short adventure.

Before implementation, describe one observable completion condition. Good examples include placing every puzzle piece, reaching a visible maze goal, or finding the named set. Loading the page, waiting for a timer, or tapping any object once is not completion.

## Write acceptance criteria first

Use Given/When/Then acceptance criteria that describe visible behavior rather than code or libraries:

- Given the level has not been completed
- When the child completes its observable task
- Then one durable star is added
- And repeating the same level celebrates again without adding another star

Document at least two edge cases: an incorrect action and an interrupted gesture. Also cover sound off, reduced motion, unavailable storage, a direct game URL, and a repeated completion signal when they apply.

## Use AI deliberately

Ask the agent to read `AGENTS.md` and `docs/GAME_DESIGN.md` completely before editing. Give it the child job, observable completion, acceptance criteria, age range, supported input, and exact safety invariants. Ask it to work test-first and to keep the game self-contained.

AI is useful for generating a first implementation, tests, original visual exploration, accessibility audits, and responsive checks. Do not accept copied characters, trademarked worlds, unverifiable assets, placeholder controls, hidden telemetry, or a result that has not been played in a real browser.

## Keep the release SLC

A first release must be:

- Simple: one narrow core loop that can be understood immediately.
- Lovable: original art, pleasant feedback, and a result worth repeating.
- Complete: catalog to game to completion to star to catalog, without a dead end.

A half-built menu, future-level placeholder, or technical framework without a finished child route does not enter the public catalog.

## Repository contract

1. Create or change one folder under `games/<slug>/`.
2. Use relative runtime paths and pin CDN dependencies to exact versions.
3. Keep every interactive control at least 44 × 44 CSS pixels.
4. Preserve the shared home, sound, fullscreen, and star behavior.
5. Add or update the implemented entry in `games-catalogue.json`.
6. Add the public card, cover, structured metadata, and detailed catalog description.
7. Provide logic tests and browser evidence for desktop, iPad portrait, iPad landscape, and a 375 px phone.

## Test-first workflow

Run the relevant failing test before production changes, make the smallest behavior change that passes it, and then run the complete suite:

```sh
node --test tests/*.test.mjs games/*/tests/*.test.mjs
TOKENVILLE_BASE_URL=http://127.0.0.1:8766 python3 tests/browser_verify.py
```

Browser verification must reject console errors, HUD overflow, covered global controls, and blank or flat 3D canvases. A release also needs a production run against `https://tokenville.ai` until the new domain is purchased and migrated.

## Original work and licensing

Only contribute work you have the right to license. Code contributions are accepted under MIT; original media and game-design content are accepted under CC BY 4.0. Identify third-party material and preserve its notice instead of silently relicensing it.