Implement file system API and add shutdown functionality for desktop builds

core/include/nova64_core.h

@@ -1,9 +1,10 @@
 #ifndef NOVA64_CORE_H
 #define NOVA64_CORE_H
 
+#include <stdarg.h>
 #include <stdbool.h>
 #include <stdint.h>
-#include <stdarg.h>
+
 
 // Cross-platform DLL export/import visibility macros
 #if defined(_WIN32) || defined(__CYGWIN__)
@@ -42,16 +43,27 @@ typedef void (*nova64_audio_output_cb_t)(const int16_t *samples,
                                          uint32_t count);
 
 /**
- * @brief Callback to read sectors from the SD card.
- * @param sector_idx The zero-based sector index to read.
- * @param destination_buffer Pointer to memory where sector data should be
- * copied.
- * @param sector_count Number of 512-byte sectors to read.
- * @return True on success, false on read error.
+ * @brief Callback to read data from the SD card.
+ * @param slot_idx Zero-based cartridge slot index.
+ * @param file_path Null-terminated path to the file to read.
+ * @param destination_buffer Pointer to memory where file data should be copied.
+ * @param destination_length Maximum number of bytes available in the
+ * destination buffer.
+ * @return Number of bytes read on success, negative value on read error.
  */
-typedef bool (*nova64_sd_read_sector_cb_t)(uint32_t sector_idx,
-                                           uint8_t *destination_buffer,
-                                           uint32_t sector_count);
+typedef int32_t (*nova64_sd_read_file_cb_t)(uint32_t slot_idx,
+                                            const char *file_path,
+                                            uint8_t *destination_buffer,
+                                            uint32_t destination_length);
+
+/**
+ * @brief Callback to retrieve the size of a file on the SD card.
+ * @param slot_idx Zero-based cartridge slot index.
+ * @param file_path Null-terminated path to the file.
+ * @return File size in bytes on success, negative value on error.
+ */
+typedef int32_t (*nova64_sd_get_file_size_cb_t)(uint32_t slot_idx,
+                                                 const char *file_path);
 
 /**
  * @brief Callback triggered when a cartridge state change occurs (e.g.
@@ -60,7 +72,7 @@ typedef bool (*nova64_sd_read_sector_cb_t)(uint32_t sector_idx,
  * @param is_inserted True if a cartridge is detected, false if ejected.
  */
 typedef void (*nova64_cartridge_status_cb_t)(uint32_t slot_idx,
-                                            bool is_inserted);
+                                             bool is_inserted);
 
 /**
  * @brief Callback for core log output.
@@ -79,7 +91,8 @@ typedef void (*nova64_log_cb_t)(const char *message);
 typedef struct {
   nova64_display_flush_cb_t display_flush;
   nova64_audio_output_cb_t audio_output;
-  nova64_sd_read_sector_cb_t sd_read_sector;
+  nova64_sd_read_file_cb_t sd_read_file;
+  nova64_sd_get_file_size_cb_t sd_get_file_size;
   nova64_cartridge_status_cb_t cartridge_status;
   nova64_log_cb_t log_message;
 } nova64_io_interface_t;
@@ -104,11 +117,13 @@ NOVA64_API bool nova64_init(const nova64_io_interface_t *io_interface);
  */
 NOVA64_API int32_t nova64_main();
 
+#if defined(NOVA64_SHUTDOWN_AVAILABLE)
 /**
  * @brief Requests shutdown of the FreeRTOS scheduler.
  * @return True if the shutdown request was issued, false otherwise.
  */
 NOVA64_API bool nova64_shutdown(void);
+#endif
 
 /**
  * @brief Retrieves the engine version integer.

core/include/nova64_fs.h

@@ -0,0 +1,39 @@
+#ifndef NOVA64_FS_H
+#define NOVA64_FS_H
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <stddef.h>
+
+/* ========================================================================== */
+/* File System API                                                            */
+/* ========================================================================== */
+
+/**
+ * @brief Reads a file from the filesystem into a buffer.
+ *        Supports drive identifiers: "SYS:" (internal system store),
+ *        "EXA:" (cartridge slot 0), "EXB:" (cartridge slot 1), etc.
+ * @param file_path Null-terminated file path with drive identifier
+ *                  (e.g., "SYS:/init.wasm" or "EXA:/game.wasm").
+ * @param buffer Pointer to destination buffer where file contents will be
+ *               copied.
+ * @param buffer_size Size in bytes of the destination buffer.
+ * @return True if file was successfully read into buffer, false on error
+ *         (file not found, read error, or buffer too small).
+ * @note Uses the sd_read_sector callback from nova64_io_interface_t.
+ *       The callback must be registered via nova64_init() before calling
+ *       this function.
+ */
+bool nova64_read_file_to_buffer(const char *file_path, uint8_t *buffer,
+                                size_t buffer_size);
+
+/**
+ * @brief Gets the size of a file in the filesystem.
+ * @param file_path Null-terminated file path with drive identifier
+ *                  (e.g., "SYS:/init.wasm" or "EXA:/game.wasm").
+ * @return Size of the file in bytes on success, or -1 on error
+ *         (file not found, read error, etc.).
+ */
+int32_t nova64_get_file_size(const char *file_path);
+
+#endif // NOVA64_FS_H

core/include/nova64_internal.h

@@ -1,6 +1,10 @@
 #ifndef NOVA64_INTERNAL_H
 #define NOVA64_INTERNAL_H
 
+#include "nova64_core.h"
+
 void nova64_log(const char *format, ...);
 
+const nova64_io_interface_t *nova64_get_io_interface(void);
+
 #endif // NOVA64_INTERNAL_H

core/include/wasm_runner.h

@@ -4,12 +4,6 @@
 #include <stdbool.h>
 #include <stdint.h>
 
-typedef enum {
-  wasm_runner_role_main = 0,
-  wasm_runner_role_status,
-  wasm_runner_role_background,
-} wasm_runner_role_t;
-
 typedef struct wasm_runner_instance wasm_runner_instance_t;
 
 typedef struct {