# Development

## Prerequisites

- MoonBit with native-target support.
- Network access only when MoonCake dependencies need to be resolved or updated.

The library is intentionally a single pure MoonBit package. Do not add a CLI,
filesystem operations, or native image library bindings. Callers own path layout
and file I/O.

## Scope

This is Orbit's image companion, not a general image-processing framework. Add a
codec or transform only when Orbit needs it. Prefer a small local implementation
when it preserves the existing bounded in-memory contract. When a required
capability would materially increase the library's complexity, evaluate a pure
MoonBit dependency behind this package's API rather than leaking that dependency
into Orbit.

The local `ref/` directory is ignored by Git and may contain unpacked MoonCake
libraries for implementation comparison. It is reference material only and must
not become a build input or a published dependency.

## Local Workflow

Install dependencies and run the normal verification loop from the repository
root:

```powershell
moon check
moon test
moon fmt
moon info
```

`moon info` regenerates `pkg.generated.mbti`. Review that file whenever a public
type or function changes; it is the package's checked public surface.

## Continuous Integration

GitHub Actions runs on pushes to `main`, pull requests targeting `main`, and
manual dispatches. The workflow checks formatting and generated public APIs,
tests native debug and release builds on Linux, macOS, and Windows, and tests
the JS, wasm, and wasm-gc targets on Ubuntu. A separate package job validates
the distributable archive.

Reproduce the target matrix locally with:

```powershell
moon test --target native --deny-warn
moon test --target js --deny-warn
moon test --target wasm --deny-warn
moon test --target wasm-gc --deny-warn
```

Run `moon test` after codec, scaling, or container changes. Tests should cover
both output bytes and rejected malformed input where applicable. Do not update
snapshots merely to accept an unexpected encoding or decoding change.

## Implementation Rules

- Keep public operations memory-only: `Bytes -> Image -> Bytes`.
- Enforce resource bounds before image-sized allocation or decompression.
- Preserve alpha through decode, resize, and encode. Resampling must operate in
  premultiplied-alpha space.
- Keep PNG output deterministic: no timestamps, random metadata, or platform
  dependent encoder paths.
- ICO and ICNS must embed PNG payloads generated by this package.
- Add dependencies through MoonCake only when they are pure MoonBit and needed.
  Remove them from `moon.mod` and `moon.pkg` when no longer used.

## Pull Requests

Keep each PR narrowly scoped and include a concise description of the behavior,
resource-limit impact, public API changes, and commands used for verification.
Public API changes require tests, README updates, and an intentional
`pkg.generated.mbti` review.

External contributor PRs require at least one `LGTM` from a repository member
before merge. The author's own approval does not count. A member merges only
after required checks pass and all review conversations are resolved.