# Capability Spec: image **Package**: `@suaveplan/image` **Status**: STABLE > Every requirement below carries a `**Verified by:**` line at authoring time. ## ADDED Requirements ### Requirement: Stable error code registry via defineCodes The package SHALL declare a single `defineCodes("IMAGE", [...])` registry named `IMAGE_CODES` containing every error code emitted by the package. No hand-typed string literals for codes SHALL appear in `src/` or tests. #### Scenario: Code values use IMAGE.* namespace - **WHEN** a consumer reads `IMAGE_CODES.NOT_FOUND` - **THEN** the value is exactly `"IMAGE.NOT_FOUND"` #### Scenario: Every code is listed in the registry - **WHEN** introspecting `IMAGE_CODES` - **THEN** it contains `NOT_FOUND`, `DECODE_FAILED`, `ENCODE_FAILED`, `FORMAT_UNSUPPORTED`, `TOO_LARGE`, `PROCESSING_FAILED`, `DIMENSIONS_INVALID` **Verified by:** `src/error-codes/error-codes.test.ts::"code values use IMAGE.* namespace"` AND `src/error-codes/error-codes.test.ts::"contains expected codes"` --- ### Requirement: Typed error hierarchy extending SuaveplanError The package SHALL export `ImageError` extending `SuaveplanError` with an optional `ImageErrorContext` carrying `format`, `width`, `height`, `pixels`, `maxPixels`, and `path`. Typed factory functions SHALL exist for every failure mode. #### Scenario: ImageError carries code, message, context, and cause - **WHEN** constructing `new ImageError(IMAGE_CODES.FORMAT_UNSUPPORTED, "msg", { format: "heic" })` - **THEN** `error.code === "IMAGE.FORMAT_UNSUPPORTED"`, `error.context.format === "heic"`, and `error instanceof SuaveplanError` is true #### Scenario: Factory functions produce correctly-coded errors - **WHEN** calling `imageNotFound("/a.png")`, `imageDecodeFailed("png")`, `imageTooLarge(10, 5)`, `imageDimensionsInvalid(-1, 0)` - **THEN** each result has the matching `IMAGE.*` code and populated context **Verified by:** `src/errors/errors.test.ts::"creates error with code and message"` AND `src/errors/errors.test.ts::"factory functions produce correctly-coded errors"` --- ### Requirement: Magic-byte format detection The package SHALL detect image formats from the first bytes of a `Uint8Array` for PNG, JPEG, GIF, BMP, TIFF (little- and big-endian), ICO, WebP, and SVG. Unknown headers SHALL return `null`. #### Scenario: Detect PNG from header - **WHEN** calling `detectFormat(new Uint8Array([0x89, 0x50, 0x4e, 0x47]))` - **THEN** the result is `"png"` #### Scenario: Reject RIFF without WEBP tag - **WHEN** calling `detectFormat` on a RIFF header whose bytes 8-11 are not `WEBP` - **THEN** the result is `null` #### Scenario: Detect SVG from textual header - **WHEN** calling `detectFormat` on a UTF-8 buffer containing `