---@meta hexis/skyblock/farming

---Generated declarations. Requires the matching Hexis build; live acceptance is pending.
local M = {}

---@class HexisFarmPoint
---@field x number
---@field y number
---@field z number

---@class HexisMarkedFarm
---@field crop string
---@field layout 's_shape'|'fixed_rows'
---@field tool {name_patterns: string[]}
---@field look {angles: {yaw: number, pitch: number}}
---@field first_row {start: HexisFarmPoint, finish: HexisFarmPoint}
---@field rows integer
---@field lane_offset HexisFarmPoint
---@field bounds {min: HexisFarmPoint, max: HexisFarmPoint}

---@class HexisFarmOptions
---@field farm HexisMarkedFarm
---@field harvest? boolean
---@field max_seconds? number
---@field start_segment? integer

---@class HexisFarmResult
---@field ok boolean
---@field reason? string
---@field message? string
---@field checkpoint? {segment: integer}
---@field segments? table[]
---@field world_generation? integer

---@param options HexisFarmOptions Farm configuration in options.farm.
---@return HexisFarmResult result Read-only validation, segments, and world generation.
function M.inspect(options) end

---@param options HexisFarmOptions Farm configuration and a finite max_seconds budget.
---@return HexisFarmResult result Completion or failure, including the last segment checkpoint.
function M.run(options) end

---@class HexisFarmRows
---@field layout 'Parallel rows sideways'|'Parallel rows lengthwise'|'Single lane sideways'|'Single lane lengthwise'
---@field crop string
---@field mode 'inspect'|'walk'|'harvest'
---@field row_length number
---@field rows integer
---@field lane_spacing? number
---@field yaw number Absolute Minecraft yaw, independent of starting camera direction.
---@field pitch number
---@field reverse? boolean
---@field tool? {name_patterns: string[]}
---@field max_seconds? number

---@param options HexisFarmRows Finite layout anchored at the player; no automatic row detection.
---@return HexisFarmResult result Shared inspection, walking or harvesting result.
function M.run_rows(options) end

---@class HexisFarmingDefinition: HexisFarmingRecipe
---@field name? string Crop display name for the default HUD.
---@field products? string[] Item IDs tracked for profit; omit to skip default profit presentation.
---@field quantity_groups? table[] Raw and compacted item conversions for profit tracking.
---@field byproducts? string[] Tracked products excluded from the main collected quantity.

---@class HexisHarvestOptions
---@field preferred_tool? string Optional first-choice hotbar tool pattern.
---@field yaw? number Fixed Minecraft yaw in degrees, including decimals; supply pitch too.
---@field pitch? number Fixed pitch in degrees, -85 through 85; supply yaw too.
---@field row_keys? string Auto, W, A, S, D, W+A, W+D, S+A, or S+D.
---@field turn_keys? string Same choices as row_keys; must move across the detected row.
---@field return_keys? string Explicit return-row keys; Auto reverses custom row keys.
---@field farm_design? string Current map or Custom. Omit for direct library configuration.
---@field farm_level? string Starting Upper or Lower level. Current map selects lower inputs after landing.
---@field harvest_min_bps? number Critical rate, 1 through 30; defaults to 5. Falling below this stops the run.
---@field harvest_window_seconds? number Complete active averaging window, 1 through 60 seconds; defaults to 10.
---@field harvest_warning_bps? number Warning threshold, at least the critical rate and at most 40; defaults to 15.
---@field harvest_warning_seconds? number Sustained warning duration, 0 through 60 seconds; defaults to 15.
---@field row_switch_delay_ms? number[] Minimum and maximum row-switch delay in milliseconds, 0 through 500.
---@field recommended_speed? number Advisory in-game speed, not movement blocks per second.
---@field value_as? string Raw, Enchanted (160 raw units), or Compacted (largest verified form); estimate only.
---@field remember_direction? boolean Reuse a validated nearby checkpoint on manual start; defaults to false for direct library calls.

---@param recipe HexisFarmingDefinition Lua crop rules, farm defaults and optional profit metadata.
---@param options? HexisHarvestOptions Optional tool, fixed angles, movement keys and health settings.
---@return HexisFarmResult result Failure explaining why continuous harvesting stopped.
function M.harvest(recipe, options) end

---@class HexisFarmSurvey
---@field ok boolean Whether a supported lane was identified.
---@field reason? string Failure category.
---@field message? string Explanation when no lane could be identified.
---@field plan? table Selected walking direction, camera angles, and any observed connector.
---@field evidence? table Bounded player and terrain observations, including first_tick and last_tick on terrain.

---@param recipe HexisFarmingDefinition Lua crop rules, farm defaults and optional profit metadata.
---@param options? HexisHarvestOptions Optional fixed angles and movement keys; no tool is selected.
---@return HexisFarmSurvey result Read-only survey; does not aim, move, or harvest.
function M.survey(recipe, options) end

---@param options HexisFarmingSessionOptions Lua recipe, optional settings, presentation and activities.
---@return table session A single-use session with run(); presentation receives native snapshots.
function M.session(options) end

return M