export * from "@common/documents/_types.mjs";

/**
 * @import {RegionMovementSegmentType, TokenShapeType} from "@common/constants.mjs";
 * @import {EffectChangeData, EffectDurationData, TokenPosition, TokenData} from "@common/documents/_types.mjs";
 * @import Roll from "@client/dice/roll.mjs";
 * @import {GridMeasurePathCostFunction3D, GridOffset3D} from "@common/grid/_types.mjs";
 * @import {DataModel, Document} from "@common/abstract/_module.mjs";
 * @import {DeepReadonly, ElevatedPoint, TokenConstrainMovementPathOptions, TokenCreateTerrainMovementPathOptions,
 *   TokenMovementActionConfig, TokenMeasureMovementPathOptions, TokenPanningOptions} from "../_types.mjs";
 * @import {ActiveEffect, Actor, Combat, Combatant, Folder, Item, RegionDocument, TableResult, TokenDocument,
 *   User} from "./_module.mjs";
 * @import {DataField} from "@common/data/fields.mjs";
 * @import {DataSchema} from "@common/abstract/_types.mjs";
 * @import ActiveEffectConfig from "@client/applications/sheets/active-effect-config.mjs";
 * @import {CanvasAnimationEasingFunction} from "@client/canvas/animation/_types.mjs";
 * @import {CompendiumCollection} from "./collections/_module.mjs";
 */

/**
 * @typedef AdventureImportData
 * The data that is planned to be imported for the adventure, categorized into new documents that will be created and
 * existing documents that will be updated.
 * @property {Record<string, object[]>} toCreate    Arrays of document data to create, organized by document name
 * @property {Record<string, object[]>} toUpdate    Arrays of document data to update, organized by document name
 * @property {number} documentCount                 The total count of documents to import
 */

/**
 * @callback AdventurePreImportCallback
 * A callback function that is invoked and awaited during import data preparation before the adventure import proceeds.
 * This can be used to perform custom pre-processing on the import data.
 * @param {AdventureImportData} data
 * @param {AdventureImportOptions} options
 * @returns {Promise<void>}
 */

/**
 * @typedef AdventureImportOptions
 * Options which customize how the adventure import process is orchestrated.
 * Modules can use the preImportAdventure hook to extend these options by adding preImport or postImport callbacks.
 * @property {boolean} [dialog=true]                Display a warning dialog if existing documents would be overwritten
 * @property {string[]} [importFields]              A subset of adventure fields to import
 * @property {AdventurePreImportCallback[]} [preImport]   An array of awaited pre-import callbacks
 * @property {AdventurePostImportCallback[]} [postImport] An array of awaited post-import callbacks
 */

/**
 * @typedef AdventureImportResult
 * A report of the world Document instances that were created or updated during the import process.
 * @property {Record<string, Document[]>} created Documents created as a result of the import, grouped by document name
 * @property {Record<string, Document[]>} updated Documents updated as a result of the import, grouped by document name
 * @property {number} importedTime                The server-side timestamp when the content was imported.
 */

/**
 * @callback AdventurePostImportCallback
 * A callback function that is invoked and awaited after import but before the overall import workflow concludes.
 * This can be used to perform additional custom adventure setup steps.
 * @param {AdventureImportResult} result
 * @param {AdventureImportOptions} options
 * @returns {Promise<void>}
 */

/**
 * @typedef _ActiveEffectChangeData
 * {@ignore}
 * @property {ActiveEffect} [effect] The parent Effect
 * @property {number} priority       The order in which this change is applied among other changes in a common phase
 */

/**
 * @typedef {EffectChangeData & _ActiveEffectChangeData} ActiveEffectChangeData
 * {@interface}
 */


/**
 * @callback ActiveEffectChangeRenderer
 * A function to render a stringified HTMLLIElement in the changes tab of {@link ActiveEffectConfig}
 * @param {object} context                 Contextual data for rendering the row
 * @param {object} context.change          A copy of the change from the ActiveEffect's source array
 * @param {number} context.index           The object's index in the changes Array
 * @param {DataSchema} context.fields
 * @param {number} context.defaultPriority The change type's default priority
 * @returns {Promise<string>}
 */

/**
 * @callback ActiveEffectChangeHandler
 * A function that applies the change to a document
 * @param {Actor|Item|TokenDocument} targetDoc The Document requesting the change application
 * @param {ActiveEffectChangeData} change      The change data
 * @param {object} [options]                   Additional options to configure the change application.
 * @param {DataField} [options.field]  The field. If not supplied, it will be retrieved from the supplied model.
 * @param {Record<string, unknown>} [options.replacementData] Data used to resolve "@" expressions.
 * @param {boolean} [options.modifyTarget]                    Modify the target Document with the updated value.
 * @returns {Promise<Record<string, unknown>|void>} A Promise resolving to either a record of Actor-data overrides made
 *                                                  or void
 */

/**
 * @typedef _ActiveEffectDuration
 * {@ignore}
 * @property {number|null} seconds       The total duration in seconds
 * @property {number} remaining          The remaining effect duration in a quantity of the configured unit
 * @property {number} [secondsRemaining] The remaining effect duration in seconds, given it is possible to express
 * @property {string} label              A formatted string label that represents the remaining duration
 * @property {number} [_worldTime]       An internal flag used determine when to recompute seconds-based duration
 * @property {number} [_combatTime]      An internal flag used determine when to recompute turns-based duration
 */

/**
 * @typedef {EffectDurationData & _ActiveEffectDuration} ActiveEffectDuration
 * {@interface}
 */

/**
 * @typedef FolderChildNode
 * A node of a Folder-content tree
 * @property {boolean} root               Whether this is the root node of a tree
 * @property {Folder} folder              The Folder document represented by this node
 * @property {number} depth               This node's depth number in the tree
 * @property {boolean} visible            Whether the Folder is visible to the current User
 * @property {FolderChildNode[]} children Child nodes of this node
 * @property {Document[]|CompendiumCollection<Document>[]} entries Loose contents in this node
 */

/**
 * @typedef CombatHistoryData
 * @property {number} round
 * @property {number|null} turn
 * @property {string|null} tokenId
 * @property {string|null} combatantId
 */

/**
 * @typedef CombatTurnEventContext
 * @property {number} round       The round
 * @property {number} turn        The turn
 * @property {boolean} skipped    Was skipped?
 */

/**
 * @typedef {Omit<CombatTurnEventContext, "turn">} CombatRoundEventContext
 */

/**
 * @template [Data=object]
 * @typedef RegionEvent
 * @property {string} name                The name of the event
 * @property {object} data                The data of the event
 * @property {RegionDocument} region      The Region the event was triggered on
 * @property {User} user                  The User that triggered the event
 */

/**
 * @typedef {RegionEvent<{}>} RegionRegionBoundaryEvent
 * @typedef {RegionEvent<{}>} RegionRegionAnimationEvent
 * @typedef {RegionEvent<{}>} RegionBehaviorActivatedEvent
 * @typedef {RegionEvent<{}>} RegionBehaviorDeactivatedEvent
 * @typedef {RegionEvent<{}>} RegionBehaviorViewedEvent
 * @typedef {RegionEvent<{}>} RegionBehaviorUnviewedEvent
 */

/**
 * @typedef RegionTokenEnterExitEventData
 * @property {TokenDocument} token                  The Token that entered/exited the Region
 * @property {TokenMovementOperation|null} movement The movement if the Token entered/exited by moving out of the Region
 *
 * @typedef {RegionEvent<RegionTokenEnterExitEventData>} RegionTokenEnterExitEvent
 * @typedef {RegionTokenEnterExitEvent} RegionTokenEnterEvent
 * @typedef {RegionTokenEnterExitEvent} RegionTokenExitEvent
 */

/**
 * @typedef RegionTokenMoveEventData
 * @property {TokenDocument} token                The Token that moved into/out of/within the Region
 * @property {TokenMovementOperation} movement    The movement
 *
 * @typedef {RegionEvent<RegionTokenMoveEventData>} RegionTokenMoveEvent
 * @typedef {RegionTokenMoveEvent} RegionTokenMoveInEvent
 * @typedef {RegionTokenMoveEvent} RegionTokenMoveOutEvent
 * @typedef {RegionTokenMoveEvent} RegionTokenMoveWithinEvent
 */

/**
 * @typedef RegionTokenAnimateEventData
 * @property {TokenDocument} token       The Token that animated into/out of the Region
 * @property {TokenPosition} position    The position of the Token when it moved into/out of the Region
 *
 * @typedef {RegionEvent<RegionTokenAnimateEventData>} RegionTokenAnimateEvent
 * @typedef {RegionTokenAnimateEvent} RegionTokenAnimateInEvent
 * @typedef {RegionTokenAnimateEvent} RegionTokenAnimateOutEvent
 */

/**
 * @typedef RegionTokenTurnEventData
 * @property {TokenDocument} token    The Token that started/ended its Combat turn
 * @property {Combatant} combatant    The Combatant of the Token that started/ended its Combat turn
 * @property {Combat} combat          The Combat
 * @property {number} round           The round of this turn
 * @property {number} turn            The turn that started/ended
 * @property {boolean} skipped        Was the turn skipped?
 *
 * @typedef {RegionEvent<RegionTokenTurnEventData>} RegionTokenTurnEvent
 * @typedef {RegionTokenTurnEvent} RegionTokenTurnStartEvent
 * @typedef {RegionTokenTurnEvent} RegionTokenTurnEndEvent
 */

/**
 * @typedef RegionTokenRoundEventData
 * @property {TokenDocument} token    The Token
 * @property {Combatant} combatant    The Combatant of the Token
 * @property {Combat} combat          The Combat
 * @property {number} round           The round that started/ended
 * @property {boolean} skipped        Was the round skipped?
 *
 * @typedef {RegionEvent<RegionTokenRoundEventData>} RegionTokenRoundEvent
 * @typedef {RegionTokenRoundEvent} RegionTokenRoundStartEvent
 * @typedef {RegionTokenRoundEvent} RegionTokenRoundEndEvent
 */

/**
 * @typedef RegionMovementSegment
 * @property {RegionMovementSegmentType} type   The type of this segment (see {@link CONST.REGION_MOVEMENT_SEGMENTS}).
 * @property {ElevatedPoint} from               The waypoint that this segment starts from.
 * @property {ElevatedPoint} to                 The waypoint that this segment goes to.
 * @property {boolean} teleport                 Teleport between the waypoints?
 */

/**
 * @typedef RegionSegmentizeMovementPathWaypoint
 * @property {number} x                         The x-coordinate in pixels (integer).
 * @property {number} y                         The y-coordinate in pixels (integer).
 * @property {number} elevation                 The elevation in grid units.
 * @property {boolean} [teleport=false]         Teleport from the previous to this waypoint? Default: `false`.
 */

/**
 * @typedef RollTableDraw
 * An object containing the executed Roll and the produced results
 * @property {Roll} roll                The Dice roll which generated the draw
 * @property {TableResult[]} results    An array of drawn TableResult documents
 */

/**
 * @typedef SceneDimensions
 * @property {number} width        The width of the canvas.
 * @property {number} height       The height of the canvas.
 * @property {number} size         The grid size.
 * @property {PIXI.Rectangle} rect      The canvas rectangle.
 * @property {number} sceneX       The X coordinate of the scene rectangle within the larger canvas.
 * @property {number} sceneY       The Y coordinate of the scene rectangle within the larger canvas.
 * @property {number} sceneWidth   The width of the scene.
 * @property {number} sceneHeight  The height of the scene.
 * @property {PIXI.Rectangle} sceneRect The scene rectangle.
 * @property {number} distance     The number of distance units in a single grid space.
 * @property {number} distancePixels  The factor to convert distance units to pixels.
 * @property {string} units        The units of distance.
 * @property {number} ratio        The aspect ratio of the scene rectangle.
 * @property {number} maxR         The length of the longest line that can be drawn on the canvas.
 * @property {number} rows         The number of grid rows on the canvas.
 * @property {number} columns      The number of grid columns on the canvas.
 */

/**
 * @typedef SceneViewOptions
 * @property {string} [level]                The ID of the Level to view
 * @property {string[]} [controlledTokens]   The IDs of initially controlled tokens
 * @property {object} [transition]           The transition animation to used when viewing the scene
 * @property {string} [transition.type]      The type of the transition animation
 * @property {number} [transition.duration]  The duration of the transition animation
 */

/**
 * @typedef TrackedAttributesDescription
 * @property {string[][]} bar    A list of property key arrays to attributes with both a value and a max property.
 * @property {string[][]} value  A list of property key arrays to attributes that have only a value property.
 */

/**
 * @typedef TokenMovementWaypoint
 * @property {number} x                      The top-left x-coordinate in pixels (integer).
 *                                           Default: the previous or source x-coordinate.
 * @property {number} y                      The top-left y-coordinate in pixels (integer).
 *                                           Default: the previous or source y-coordinate.
 * @property {number} elevation              The elevation in grid units.
 *                                           Default: the previous or source elevation.
 * @property {number} width                  The width in grid spaces (positive).
 *                                           Default: the previous or source width.
 * @property {number} height                 The height in grid spaces (positive).
 *                                           Default: the previous or source height.
 * @property {number} depth                  The depth in grid spaces (nonnegative).
 *                                           Default: the previous or source depth.
 * @property {TokenShapeType} shape          The shape type (see {@link CONST.TOKEN_SHAPES}).
 *                                           Default: the previous or source shape.
 * @property {string} level                  The level ID. Default: the previous or source level ID.
 * @property {string} action                 The movement action from the previous to this waypoint.
 *                                           Default: the prepared movement action.
 * @property {boolean} snapped               Was this waypoint snapped to the grid? Default: `false`.
 * @property {boolean} explicit              Was this waypoint explicitly placed by the user? Default: `false`.
 * @property {boolean} checkpoint            Is this waypoint a checkpoint? There's an update/movement operation
 *                                           for each checkpoint in a movement path. At a checkpoint the movement
 *                                           can be stopped or paused. Default: `false`.
 */

/**
 * @typedef _TokenProcessedMovementWaypoint
 * {@ignore}
 * @property {DataModel|null} terrain         The terrain data of this segment. Default: `null`.
 * @property {boolean} intermediate           Is this waypoint intermediate? Default: `false`.
 */

/**
 * @typedef {TokenMovementWaypoint & _TokenProcessedMovementWaypoint} TokenProcessedMovementWaypoint
 * {@interface}
 */

/**
 * @typedef _TokenMeasuredMovementWaypoint
 * {@ignore}
 * @property {string} userId             The ID of the user that moved the token to from the previous to this waypoint.
 * @property {string|null} movementId    The ID of the movement from the previous to this waypoint, or null if pending
 *                                       but not planned.
 * @property {string} subpathId          The ID of the subpath, which is equal to the movement ID of the first waypoint
 *                                       in the subpath.
 * @property {number} cost               The movement cost from the previous to this waypoint (nonnegative).
 */

/**
 * @typedef {TokenProcessedMovementWaypoint & _TokenMeasuredMovementWaypoint} TokenMeasuredMovementWaypoint
 * {@interface}
 */

/**
 * @typedef TokenMovementSegmentData
 * @property {number} width              The width in grid spaces (positive).
 * @property {number} height             The height in grid spaces (positive).
 * @property {number} depth              The depth in grid spaces (nonnegative).
 * @property {TokenShapeType} shape      The shape type (see {@link CONST.TOKEN_SHAPES}).
 * @property {string} level              The level ID.
 * @property {string} action             The movement action of this segment.
 * @property {TokenMovementActionConfig} actionConfig  The config of the movement action.
 * @property {DataModel|null} terrain    The terrain data of this segment.
 * @property {boolean} teleport          Teleported?
 */

/**
 * @typedef TokenMeasurableMovementWaypointData
 * @property {number|TokenMovementCostFunction} [cost]    A predetermined cost (nonnegative) or cost function
 *                                                        to be used instead of `options.cost`.
 */

/**
 * @typedef {Partial<TokenProcessedMovementWaypoint>
 *   & TokenMeasurableMovementWaypointData} TokenMeasurableMovementWaypoint
 */

/**
 * @typedef {GridMeasurePathCostFunction3D<TokenMovementSegmentData>} TokenMovementCostFunction
 */

/**
 * @callback TokenMovementCostAggregator
 * @param {Array<DeepReadonly<{from: GridOffset3D, to: GridOffset3D, cost: number}>>} results
 *                                                           The results of the cost function calls.
 *                                                           The array may be sorted but otherwise not be mutated.
 * @param {number} distance                                  The distance between the grid spaces.
 * @param {DeepReadonly<TokenMovementSegmentData>} segment   The properties of the segment.
 * @returns {number}                                         The aggregated cost.
 */

/**
 * @typedef TokenRegionMovementSegment
 * @property {RegionMovementSegmentType} type     The type of this segment (see {@link CONST.REGION_MOVEMENT_SEGMENTS}).
 * @property {TokenPosition} from                 The waypoint that this segment starts from.
 * @property {TokenPosition} to                   The waypoint that this segment goes to.
 * @property {string} action                      The movement action between the waypoints.
 * @property {DataModel|null} terrain             The terrain data of this segment.
 * @property {boolean} snapped                    Is the destination snapped to the grid?
 */

/**
 * @typedef TokenMovementSectionData
 * @property {TokenMeasuredMovementWaypoint[]} waypoints    The waypoints of the movement path
 * @property {number} distance                              The distance of the movement path
 * @property {number} cost                                  The cost of the movement path
 * @property {number} spaces                                The number of spaces moved along the path
 * @property {number} diagonals                             The number of diagonals moved along the path
 */

/**
 * @typedef TokenMovementHistoryData
 * @property {TokenMovementSectionData} recorded            The recorded waypoints of the movement path
 * @property {TokenMovementSectionData} unrecorded          The unrecored waypoints of the movement path
 * @property {number} distance                              The distance of the combined movement path
 * @property {number} cost                                  The cost of the combined movement path
 * @property {number} spaces                                The number of spaces moved along the combined path
 * @property {number} diagonals                             The number of diagonals moved along the combined path
 */

/**
 * @typedef {"api"|"config"|"hud"|"dragging"|"keyboard"|"paste"|"undo"} TokenMovementMethod
 */

/**
 * @typedef {"completed"|"paused"|"planned"|"pending"|"stopped"} TokenMovementState
 */

/**
 * @typedef TokenMovementData
 * The token movement data that describes the current/last movement of the token.
 * NONE of the properties are writable.
 * @property {string} id         The ID of the movement
 * @property {string} subpathId  The ID of the subpath, which is equal to the movement ID of the first
 *                               waypoint in the subpath
 * @property {string[]} chain    The chain of prior movement IDs that this movement is a continuation of
 * @property {TokenPosition} origin                The origin of movement
 * @property {TokenPosition} destination           The destination of movement
 * @property {TokenMovementSectionData} passed     The waypoints and measurements of the passed path
 * @property {TokenMovementSectionData} pending    The waypoints and measurements of the pending path
 * @property {TokenMovementHistoryData} history    The waypoints and measurements of the history path
 * @property {boolean} split                       Was a new subpath started?
 * @property {boolean} constrained                 Was the movement constrained?
 * @property {boolean} recorded                    Was the movement recorded in the movement history?
 * @property {TokenMovementMethod} method          The method of movement
 * @property {Omit<TokenCreateTerrainMovementPathOptions, "preview">} terrainOptions
 *                                         The terrain movement options
 * @property {Omit<TokenConstrainMovementPathOptions, "preview"|"history"|"measureOptions">} constrainOptions
 *                                         The options to constrain movement
 * @property {Omit<TokenMeasureMovementPathOptions, "preview">} measureOptions
 *                                         The options to measure movement
 * @property {boolean} autoRotate          Automatically rotate the token in the direction of movement?
 * @property {boolean} showRuler           Show the ruler during the movement animation of the token?
 * @property {User} user                   The user that moved the token
 * @property {TokenMovementState} state    The state of the movement
 * @property {object} updateOptions        The update options of the movement operation
 * @property {Promise<boolean>} finished   The promise that resolves once the entire movement is finished.
 *                                         It resolves to true if the movement completed, otherwise false.
 * @property {{started: Promise<void>; ended: Promise<void>; duration: number}} animation
 *   The promise that resolves when the animation of this movement starts, the promise that resolves when
 *   the animation of this movement ends, and the duration of the animation of this movement.
 */

/**
 * @typedef TokenPreMovementOperation
 * The pre-movement operation data of a token movement.
 * ONLY `autoRotate` and `showRuler` are writable.
 * @property {string} id         The ID of the movement.
 *                               This property is NOT writable.
 * @property {string} subpathId  The ID of the subpath, which is equal to the movement ID of the first
 *                               waypoint in the subpath.
 *                               This property is NOT writable.
 * @property {string[]} chain    The chain of prior movement IDs that this movement is a continuation of.
 *                               This property is NOT writable.
 * @property {TokenPosition} origin                The origin of movement.
 *                                                 This property is NOT writable.
 * @property {TokenPosition} destination           The destination of movement.
 *                                                 This property is NOT writable.
 * @property {TokenMovementSectionData} passed     The waypoints and measurements of the passed path.
 *                                                 This property is NOT writable.
 * @property {TokenMovementSectionData} pending    The waypoints and measurements of the pending path.
 *                                                 This property is NOT writable.
 * @property {TokenMovementHistoryData} history    The waypoints and measurements of the history path.
 *                                                 This property is NOT writable.
 * @property {boolean} split                       Was a new subpath started?
 *                                                 This property is NOT writable.
 * @property {boolean} constrained                 Was the movement constrained?
 *                                                 This property is NOT writable.
 * @property {boolean} recorded                    Was the movement recorded in the movement history?
 *                                                 This property is NOT writable.
 * @property {TokenMovementMethod} method          The method of movement.
 *                                                 This property is NOT writable.
 * @property {Omit<TokenCreateTerrainMovementPathOptions, "preview">} terrainOptions
 *                                         The terrain movement options.
 *                                         This property is NOT writable.
 * @property {Omit<TokenConstrainMovementPathOptions, "preview"|"history"|"measureOptions">} constrainOptions
 *                                         The options to constrain movement.
 *                                         This property is NOT writable.
 * @property {Omit<TokenMeasureMovementPathOptions, "preview">} measureOptions
 *                                         The options to measure movement.
 *                                         This property is NOT writable.
 * @property {boolean} autoRotate          Automatically rotate the token in the direction of movement?
 *                                         This property IS writable.
 * @property {boolean} showRuler           Show the ruler during the movement animation of the token?
 *                                         This property IS writable.
 */

/**
 * @typedef TokenMovementOperation
 * The (post-)movement operation data of a token movement.
 * NONE of the properties are writable.
 * @property {string} id         The ID of the movement
 * @property {string} subpathId  The ID of the subpath, which is equal to the movement ID of the first
 *                               waypoint in the subpath.
 * @property {string[]} chain    The chain of prior movement IDs that this movement is a continuation of
 * @property {TokenPosition} origin                The origin of movement
 * @property {TokenPosition} destination           The destination of movement
 * @property {TokenMovementSectionData} passed     The waypoints and measurements of the passed path
 * @property {TokenMovementSectionData} pending    The waypoints and measurements of the pending path
 * @property {TokenMovementHistoryData} history    The waypoints and measurements of the history path
 * @property {boolean} split                       Was a new subpath started?
 * @property {boolean} constrained                 Was the movement constrained?
 * @property {boolean} recorded                    Was the movement recorded in the movement history?
 * @property {TokenMovementMethod} method          The method of movement
 * @property {Omit<TokenCreateTerrainMovementPathOptions, "preview">} terrainOptions
 *                                         The terrain movement options
 * @property {Omit<TokenConstrainMovementPathOptions, "preview"|"history"|"measureOptions">} constrainOptions
 *                                         The options to constrain movement
 * @property {Omit<TokenMeasureMovementPathOptions, "preview">} measureOptions
 *                                         The options to measure movement
 * @property {boolean} autoRotate          Automatically rotate the token in the direction of movement?
 * @property {boolean} showRuler           Show the ruler during the movement animation of the token?
 * @property {Promise<boolean>} finished   The promise that resolves once the entire movement is finished.
 *                                         It resolves to true if the movement completed, otherwise false.
 * @property {{started: Promise<void>; ended: Promise<void>; duration: number}} animation
 *   The promise that resolves when the animation of this movement starts, the promise that resolves when
 *   the animation of this movement ends, and the duration of the animation of this movement.
 */

/**
 * @typedef TokenMovementInstructionOptions
 * @property {string} [id]                   The movement ID, which must be unique. Default: auto-generated.
 * @property {TokenMovementMethod} [method]  The method of movement. Default: {@link TokenMovementOptions#method}.
 * @property {boolean} [autoRotate]  Automatically rotate the token in the direction of movement?
 *   Default: {@link TokenMovementOptions#autoRotate}.
 * @property {boolean} [showRuler]  Show the ruler during the movement animation of the token?
 *   Default: {@link TokenMovementOptions#showRuler}.
 * @property {Omit<TokenCreateTerrainMovementPathOptions, "preview">} [terrainOptions]
 *   The terrain movement options. Default: {@link TokenMovementOptions#terrainOptions}.
 * @property {Omit<TokenConstrainMovementPathOptions, "preview"|"history"|"measureOptions">} [constrainOptions]
 *   The options to constrain movement. Default: {@link TokenMovementOptions#constrainOptions}.
 * @property {Omit<TokenMeasureMovementPathOptions, "preview">} [measureOptions]  The options to measure movement.
 *   Default: {@link TokenMovementOptions#measureOptions}.
 * @property {boolean} [split]      Start a new subpath? Default: {@link TokenMovementOptions#split}.
 * @property {boolean} [planned]    Don't start the movement yet? Default: {@link TokenMovementOptions#planned}.
 */

/**
 * @typedef TokenMovementInstructionDestination
 * @property {Partial<TokenData & TokenMovementWaypoint>} destination  The destination which may include additional
 *  token data.
 */

/**
 * @typedef TokenMovementInstructionWaypoints
 * @property {Partial<TokenMovementWaypoint>[]} waypoints  The waypoints to move the token through.
 */

/**
 * @typedef {(TokenMovementInstructionDestination | TokenMovementInstructionWaypoints)
 *   & TokenMovementInstructionOptions} TokenMovementInstruction
 */

/**
 * @typedef TokenResizingInstruction
 * Resize the Token such that its center point remains (almost) unchanged. The center point might change
 * slightly because the new (x, y) position is rounded.
 * @property {Partial<Omit<TokenData & TokenMovementWaypoint, "x"|"y"|"elevation">>} dimensions
 *                                           The new dimensions and additional data.
 * @property {string} [id]                   The movement ID, which must be unique. Default: auto-generated.
 * @property {TokenMovementMethod} [method]  The method of movement. Default: {@link TokenMovementOptions#method}.
 * @property {false} [autoRotate]                                        Resizing never auto rotates.
 * @property {false} [showRuler]                                         Resizing never shows the ruler.
 * @property {{}} [terrainOptions]                                       Resizing doesn't move through terrain.
 * @property {{ignoreWalls: true, ignoreCost: true}} [constrainOptions]  Resizing always ignores walls, surfaces and
 *                                                                       impassable terrain.
 * @property {{}} [measureOptions]                                       Resizing doesn't cost anything.
 * @property {boolean} [split]      Start a new subpath? Default: {@link TokenMovementOptions#split}.
 * @property {boolean} [planned]    Don't start the movement yet? Default: {@link TokenMovementOptions#planned}.
 */

/**
 * @typedef TokenMovementOptions
 * @property {string} [id]                         The movement ID, which must be unique. Default: auto-generated.
 * @property {TokenMovementMethod} [method="api"]  The method of movement. Default: `"api"`.
 * @property {boolean} [autoRotate]  Automatically rotate the token in the direction of movement? Default:
 *   `game.settings.get("core", "tokenAutoRotate")` if `method` is `"dragging"` or `"keyboard"` otherwise `false`.
 * @property {boolean} [showRuler]  Show the ruler during the movement animation of the token? Default: `true` if
 *   `method` is `"dragging"` otherwise `false`.
 *   duration of movement. Default: `false`.
 * @property {Omit<TokenCreateTerrainMovementPathOptions, "preview">} [terrainOptions]  The terrain movement options.
 * @property {Omit<TokenConstrainMovementPathOptions, "preview"|"history"|"measureOptions">} [constrainOptions]
 *   The options to constrain movement.
 * @property {Omit<TokenMeasureMovementPathOptions, "preview">} [measureOptions]  The options to measure movement.
 * @property {boolean} [split]                           Start a new subpath? Default: `false` if it's movement
 *                                                       without history or keyboard movement that follows keyboard
 *                                                       movement, otherwise `true`.
 * @property {boolean} [planned=false]                   Don't start the movement yet? Default: `false`.
 * @property {boolean|TokenPanningOptions} [pan=true]    Pan the canvas (with transition animation) to the destination
 *                                                       if the token is controlled? Default: `true`.
 * @property {boolean} [animate=true]                    Animate movement. Default: `true`.
 * @property {object} [animation]                        The animation options.
 * @property {number} [animation.duration]               The duration of the animation in milliseconds (nonnegative).
 * @property {number} [animation.movementSpeed]          The base movement speed in grid size per second (positive).
 * @property {boolean} [animation.linkToMovement=false]  Set the duration of non-movement properties to the animation.
 * @property {CanvasAnimationEasingFunction} [animation.easing]  The easing function of the animation of non-movement
 *                                                       properties. Default: `undefined` (linear).
 */

/**
 * @typedef TokenMovementContinuationData
 * @property {string} id                                The movement continuation ID, which is equal to the movement ID
 *                                                      unless planned, in which case the continuation ID is the
 *                                                      movement ID with the ".planned" suffix
 * @property {number} continueCounter                   The number of continuations
 * @property {boolean} continued                        Was continued?
 * @property {Promise<boolean>|null} continuePromise    The continuation promise
 * @property {Promise<void>} waitPromise                The promise to wait for before continuing movement
 * @property {() => {}|undefined} resolveWaitPromise    Resolve function of the wait promise
 * @property {Promise<void>} postWorkflowPromise        The promise that resolves after the update workflow
 * @property {{[movementId: string]: {handles: Map<string|symbol|null, TokenMovementContinuationHandle>;
 *   callbacks: Array<(continued: boolean) => void>; pending: Set<string>}}} states    The movement continuation states
 */

/**
 * @typedef TokenMovementContinuationHandle
 * @property {string} continuationID                         The continuation ID
 * @property {() => Promise<boolean>} callback               The continuation callback
 * @property {Promise<boolean>|undefined} continuePromise    The continuation promise
 */

/**
 * @callback TokenResumeMovementCallback
 * @returns {Promise<boolean>}    A promise that resolves to true if the movement was resumed.
 *                                If it wasn't resumed, it resolves to false.
 */

/**
 * @typedef {"door"|"ethereal"|"invisible"|"normal"|"secret"|"terrain"|"window"|"blank"} WallCategory
 */

/**
 * @typedef RegionSurface
 * @property {string} key                     A key that uniquely identifies the surface
 * @property {RegionDocument} region          The region of the surface
 * @property {number} elevation               The elevation of the surface
 * @property {boolean} light                  Does the surface restrict light?
 * @property {boolean} move                   Does the surface restrict movement?
 * @property {boolean} sight                  Does the surface restrict sight?
 * @property {boolean} sound                  Does the surface restrict sound?
 * @property {boolean} occlusion              Does the surface cause occlusion?
 * @property {boolean} exposure               Does the surface cause exposure?
 * @property {boolean} culling                Does the surface cause culling?
 */
