Architecture in.
Software out.

# Qoizig

@id: QOI_CODEC
@status: draft
@priority: high
@depends: []

## Overview

A high-performance, zero-dependency command-line tool
and library implemented in Zig for the QOI (Quite OK
Image) format.

## Requirements

### QOI Format Fundamentals

**Header Structure:**
- `char[4]` magic: "qoif"
- `u32` width: image width in pixels (BE)
- `u32` height: image height in pixels (BE)
- `u8` channels: 3 = RGB, 4 = RGBA
- `u8` colorspace: 0 = sRGB, 1 = linear

…

### Encode Command (`qoizig encode`)

**Accepts:**
- `input` (positional, required): Path to source file
- `output` (positional, required): Path for QOI output

**Errors:**
- Input file not found -> print error and exit code 1
- Invalid PPM/PAM header -> print error and exit code 1

…

### WARNING: Encode Command

The encode command CLI example shows two positional
arguments (input and output path), but the requirement
only specifies one positional argument.

**Suggestion:** Add `output` (positional) to the
Accepts list for the encode command, and clarify
the default behavior if omitted.

# …tasks 001–002: scaffold, types…

[[task]]
id = "003"
spec = "QOI_CODEC"
title = "QOI Encoder Implementation"
outputs = ["src/encoder.zig"]
depends_on = ["001", "002"]
verify = "zig build --summary all"

[[task]]
id = "004"
spec = "QOI_CODEC"
title = "QOI Decoder Implementation"
outputs = ["src/decoder.zig"]
depends_on = ["001", "002"]
verify = "zig build --summary all"

# …tasks 005–009: tests, CLI, integration…

/// Encode raw pixel data into a complete QOI byte stream.
pub fn encode(
    allocator: std.mem.Allocator,
    pixels: []const u8,
    width: u32,
    height: u32,
    channels: Channels,
    colorspace: Colorspace,
) error{ InvalidPixelDataLength, OutOfMemory }![]u8 {
    // …validation, buffer allocation…

    // Write header
    const header = QoiHeader{
        .width = width,
        .height = height,
        .channels = channels,
        .colorspace = colorspace,
    };
    const header_bytes = header.encode();
    @memcpy(output[pos .. pos + qoi.QOI_HEADER_SIZE], &header_bytes);
    pos += qoi.QOI_HEADER_SIZE;

    // Encoder state
    var index: [qoi.QOI_INDEX_SIZE]Pixel = // …
    var prev_px: Pixel = Pixel.default;
    var run: u8 = 0;

    // …chunk compression, end marker…
}