# API Reference

This document provides a reference for the yaze C and C++ APIs, intended for developers creating extensions or contributing to the core application.

## C API (`incl/yaze.h`)

The C API provides a stable, language-agnostic interface for interacting with yaze's core functionalities.

### Core Library Functions
```c
/**
 * @brief Initializes the yaze library. Must be called before any other API function.
 * @return YAZE_OK on success, or an error code on failure.
 */
yaze_status yaze_library_init(void);

/**
 * @brief Shuts down the yaze library and releases all resources.
 */
void yaze_library_shutdown(void);

/**
 * @brief Gets the current version of the yaze library as a string.
 * @return A constant string representing the version (e.g., "0.3.2").
 */
const char* yaze_get_version_string(void);
```

### ROM Operations
```c
/**
 * @brief Loads a Zelda 3 ROM from a file.
 * @param filename The path to the ROM file.
 * @return A pointer to a zelda3_rom object, or NULL on failure.
 */
zelda3_rom* yaze_load_rom(const char* filename);

/**
 * @brief Unloads a ROM and frees associated memory.
 * @param rom A pointer to the zelda3_rom object to unload.
 */
void yaze_unload_rom(zelda3_rom* rom);

/**
 * @brief Saves a ROM to a file.
 * @param rom A pointer to the ROM to save.
 * @param filename The path to save the file to.
 * @return YAZE_OK on success.
 */
yaze_status yaze_save_rom(zelda3_rom* rom, const char* filename);
```

## C++ API

The C++ API offers a more powerful, object-oriented interface. The primary entry point for many operations is the `yaze::core::AsarWrapper` class.

### AsarWrapper (`src/core/asar_wrapper.h`)

This class provides a complete, cross-platform interface for applying assembly patches, extracting symbols, and validating assembly code using the Asar library.

#### CLI Examples (`z3ed`)

While the `AsarWrapper` can be used programmatically, the `z3ed` CLI is the most common way to interact with it.

```bash
# Apply an assembly patch to a ROM file.
z3ed asar my_patch.asm --rom=zelda3.sfc

# For more complex operations, use the AI agent.
z3ed agent chat --rom zelda3.sfc
```
> **Prompt:** "Apply the patch `mosaic_change.asm` to my ROM."

#### C++ API Example
```cpp
#include "core/asar_wrapper.h"
#include <vector>
#include <string>

// Assume rom_data is a std::vector<uint8_t> holding the ROM content.
yaze::core::AsarWrapper wrapper;
wrapper.Initialize();

// Apply a patch to the ROM data in memory.
auto result = wrapper.ApplyPatch("patch.asm", rom_data);

if (result.ok() && result->success) {
    // On success, print the symbols generated by the patch.
    for (const auto& symbol : result->symbols) {
        std::cout << symbol.name << " @ $" << std::hex << symbol.address << std::endl;
    }
}
```

#### Class Definition
```cpp
namespace yaze::core {

class AsarWrapper {
public:
    /** @brief Initializes the Asar library. */
    absl::Status Initialize();

    /** @brief Shuts down the Asar library. */
    void Shutdown();

    /**
     * @brief Applies an assembly patch to ROM data.
     * @param patch_path Path to the main .asm file.
     * @param rom_data A vector of bytes representing the ROM data.
     * @param include_paths Optional paths for Asar to search for included files.
     * @return A StatusOr containing the patch result, including success status and symbols.
     */
    absl::StatusOr<AsarPatchResult> ApplyPatch(
        const std::string& patch_path,
        std::vector<uint8_t>& rom_data,
        const std::vector<std::string>& include_paths = {});

    /**
     * @brief Extracts symbols from an assembly file without patching.
     * @param asm_path Path to the .asm file.
     * @return A StatusOr containing a vector of extracted symbols.
     */
    absl::StatusOr<std::vector<AsarSymbol>> ExtractSymbols(
        const std::string& asm_path,
        const std::vector<std::string>& include_paths = {});

    /**
     * @brief Validates the syntax of an assembly file.
     * @param asm_path Path to the .asm file.
     * @return An OK status if syntax is valid, or an error status if not.
     */
    absl::Status ValidateAssembly(const std::string& asm_path);
};

} // namespace yaze::core
```

## Data Structures

### `snes_color`
Represents a 15-bit SNES color, composed of 5 bits for each red, green, and blue component.
```c
typedef struct snes_color {
    uint16_t raw;   //!< Raw 15-bit BGR color value (0bbbbbgggggrrrrr).
    uint8_t red;    //!< Red component (0-31).
    uint8_t green;  //!< Green component (0-31).
    uint8_t blue;   //!< Blue component (0-31).
} snes_color;
```

### `zelda3_message`
Represents an in-game text message.
```c
typedef struct zelda3_message {
    uint16_t id;            //!< The message ID (0-65535).
    uint32_t rom_address;   //!< The address of the message data in the ROM.
    uint16_t length;        //!< The length of the raw message data in bytes.
    uint8_t* raw_data;      //!< A pointer to the raw, compressed message data.
    char* parsed_text;      //!< The decoded, human-readable UTF-8 text.
    bool is_compressed;     //!< Flag indicating if the message data is compressed.
}
zelda3_message;
```

## Error Handling

The C API uses an enum `yaze_status` for error handling, while the C++ API uses `absl::Status` and `absl::StatusOr`.

### C API Error Pattern
```c
yaze_status status = yaze_library_init();
if (status != YAZE_OK) {
    fprintf(stderr, "Failed to initialize YAZE: %s\n", yaze_status_to_string(status));
    return 1;
}

// ... operations ...

yaze_library_shutdown();
```