# Contributing

Thanks for helping improve dsh-pixel-studio. This project follows the
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin
model and keeps the host half dependency-free.

## Development setup

Requirements:

- Node.js 20+
- DeepSeek Harness 0.2.1-rc.2+ within 0.2.x
- Git

```bash
git clone git@github.com:Fantety/dsh-pixel-studio.git
cd dsh-pixel-studio
npm test
npm run check
```

There is no build step. `lib/index.js` is the host entry and `lib/client.js` is
a hand-written `window.__ModuleLoader__.load` client factory.

## Local DSH testing

Link the checkout into a CLI-managed profile. Replace `my-profile` with its
name; the `desktop` profile must be managed through the DSH Plugin Manager
instead.

```bash
cd ~/.dsh/profiles/my-profile
pnpm add "link:/absolute/path/to/dsh-pixel-studio"
```

Then add `"dsh-pixel-studio"` to `dsh.profile.bundles` in that profile's
`package.json`. The package's own `cordis.patch.yml` inserts the `pixel-studio`
row, so do **not** also copy that row into the profile patch layer. Remove an
old manual `pixel-studio` insert if one is still present.

Reload DSH, then refresh the Web GUI once to pick up the client bundle.

## What to change

- **Host logic** lives in `lib/`, split by responsibility under `lib/pixel/`.
- **Client UI and canvas** lives in `lib/client.js`.
- **Craft guidance** lives in `lib/craft-prompt.js`; keep it concise because it
  is inserted into every model step while the plugin is mounted.
- **Tests** live in `test/`; add a regression test for behavior changes.
- **Examples** are generated by the scripts. If you intentionally change demo
  output, run both demo scripts and include the updated files.

## Style

- Node ESM, 2-space indentation, LF line endings.
- No new runtime dependencies without a clear reason; the host half must keep
  working with Node built-ins.
- Validate all model-supplied grids, palettes, frame sizes and output limits
  before writing files.
- Preserve deterministic output and transparent fallbacks.
- Keep client code compatible with the React runtime supplied by DSH; do not
  bundle React.

## Tests and checks

```bash
npm test
npm run check
npm pack --dry-run
```

The suite covers PNG/GIF encoding, OYPX rows, animation timing, inline canvas
budgets, craft checks, schema registration, and client registration.

## Pull requests

- Keep PRs focused; describe the user-visible change and any security impact.
- Add or update tests.
- Do not commit local paths, credentials, generated `pixel-art/` output, or
  `node_modules`.
- By contributing, you agree that your contribution is licensed under the
  project's [MIT License](LICENSE).

## Reporting bugs and security issues

Use the issue templates for normal bugs and feature requests. For security
issues, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.