/**
 * aviation_queue.h — Queue manager for the domain core.
 *
 * Manages a playlist of media items with:
 * - Ordered item storage (up to AVIATION_MAX_QUEUE_SIZE)
 * - Current index tracking
 * - Shuffle support (Fisher-Yates with current-item-first guarantee)
 * - Repeat modes (off, one, all)
 * - Next/previous index resolution respecting shuffle + repeat
 * - Insert/remove/move operations with index adjustment
 *
 * The queue manager is NOT thread-safe on its own.
 * The coordinator must hold its mutex before calling queue methods.
 *
 * Pure C. No platform imports.
 */

#ifndef AVIATION_QUEUE_H
#define AVIATION_QUEUE_H

#include "aviation_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/** Opaque handle to a queue manager instance. */
typedef struct AviationQueueManager AviationQueueManager;

/* ─── Lifecycle ───────────────────────────────────────────────────── */

/** Create a new queue manager. */
AviationQueueManager *aviation_queue_create(void);

/** Destroy a queue manager and free all resources. */
void aviation_queue_destroy(AviationQueueManager *queue);

/* ─── Queue mutation ──────────────────────────────────────────────── */

/**
 * Set the entire queue contents, replacing any existing items.
 * Items are copied into the queue. Sets current index to 0 if non-empty.
 * Returns 0 on success, -1 if count exceeds AVIATION_MAX_QUEUE_SIZE.
 */
int aviation_queue_set(AviationQueueManager *queue, const AviationMediaItem *items, int count);

/**
 * Append an item to the end of the queue.
 * Returns 0 on success, -1 if queue is full.
 */
int aviation_queue_add(AviationQueueManager *queue, const AviationMediaItem *item);

/**
 * Insert an item after the given index.
 * Returns 0 on success, -1 on invalid index or queue full.
 */
int aviation_queue_insert_after(AviationQueueManager *queue, const AviationMediaItem *item, int after_index);

/**
 * Remove the item at the given index.
 * Adjusts the current index appropriately:
 * - If removing before current: current index decrements
 * - If removing current: clamps to valid range
 * Returns 0 on success, -1 on invalid index.
 */
int aviation_queue_remove(AviationQueueManager *queue, int index);

/**
 * Move an item from one index to another.
 * Adjusts the current index appropriately.
 * Returns 0 on success, -1 on invalid indices.
 */
int aviation_queue_move(AviationQueueManager *queue, int from_index, int to_index);

/**
 * Clear all items from the queue.
 */
void aviation_queue_clear(AviationQueueManager *queue);

/* ─── Navigation ──────────────────────────────────────────────────── */

/**
 * Resolve the next index based on current position, shuffle, and repeat mode.
 * Returns the next index, or -1 if there is no next item (queue end).
 */
int aviation_queue_resolve_next(const AviationQueueManager *queue);

/**
 * Resolve the next N indices from the current position.
 * Writes up to max_count indices into out_indices, respecting shuffle and repeat.
 * Returns the number of indices actually written (0 to max_count).
 *
 * For REPEAT_ONE, returns the current index repeated up to max_count times.
 * For REPEAT_ALL, wraps around the queue/shuffle order.
 * For REPEAT_OFF, stops at the end of the queue.
 *
 * Does NOT modify the queue state — this is a read-only lookahead.
 */
int aviation_queue_resolve_next_n(const AviationQueueManager *queue, int *out_indices, int max_count);

/**
 * Resolve the previous index based on current position, shuffle, and repeat mode.
 * Returns the previous index, or -1 if there is no previous item.
 */
int aviation_queue_resolve_previous(const AviationQueueManager *queue);

/* ─── State queries ───────────────────────────────────────────────── */

/** Get the current queue index. -1 if queue is empty. */
int aviation_queue_get_index(const AviationQueueManager *queue);

/** Set the current queue index. */
void aviation_queue_set_index(AviationQueueManager *queue, int index);

/** Get the number of items in the queue. */
int aviation_queue_get_count(const AviationQueueManager *queue);

/** Get a pointer to the item at the given index. NULL if invalid. */
const AviationMediaItem *aviation_queue_get_item(const AviationQueueManager *queue, int index);

/** Get a pointer to the items array (for iteration). */
const AviationMediaItem *aviation_queue_get_items(const AviationQueueManager *queue);

/** Check if the queue is empty. */
bool aviation_queue_is_empty(const AviationQueueManager *queue);

/* ─── Shuffle ─────────────────────────────────────────────────────── */

/** Enable or disable shuffle mode. Rebuilds the shuffle order. */
void aviation_queue_set_shuffle(AviationQueueManager *queue, bool enabled);

/** Get whether shuffle is enabled. */
bool aviation_queue_get_shuffle(const AviationQueueManager *queue);

/* ─── Repeat mode ─────────────────────────────────────────────────── */

/** Set the repeat mode. */
void aviation_queue_set_repeat(AviationQueueManager *queue, AviationRepeatMode mode);

/** Get the repeat mode. */
AviationRepeatMode aviation_queue_get_repeat(const AviationQueueManager *queue);

#ifdef __cplusplus
}
#endif

#endif /* AVIATION_QUEUE_H */