backend-infra-engineer: Release v0.3.3 snapshot

docs/public/developer/api-reference.md

@@ -0,0 +1,181 @@
+# 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();
+```