import { StorageElementType, CanvasBaseInterface, ImageSprite, ShakeEffectProps, ShowWithDissolveTransitionProps, ShowWithFadeTransitionProps, MoveInOutProps, ZoomInOutProps, PushInOutProps, ImageContainerOptions, ImageSpriteOptions, TextOptions, ImageSpriteMemory, VideoSpriteMemory, ImageContainerMemory, TextMemory, ContainerOptions, ContainerMemory, SoundPlayOptionsWithChannel, MediaInterface, LabelRunModeType, StorageObjectType, StepLabelPropsType } from '@drincs/pixi-vn';
import { ZodType } from 'zod';
export * from '@drincs/pixi-vn-json/core';
export * from '@drincs/pixi-vn-json/interpreter';
import { KeyframesType, AnimationOptions, ObjectSegment, ObjectSegmentWithTransition, SequenceOptions } from '@drincs/pixi-vn/motion';
import { UPDATE_PRIORITY } from 'pixi.js';
export * from '@drincs/pixi-vn-json/translator';

/**
 * A single element that can appear inside a step-switch, which may be a direct value,
 * a conditional statement, or a result-to-combine.
 */
type PixiVNJsonStepSwitchElementType<Then> = Then | PixiVNJsonConditionalStatements<Then> | PixiVNJsonConditionalResultToCombine<Then>;
/**
 * The elements collection of a step-switch — either a plain array or a conditional that produces an array.
 */
type PixiVNJsonStepSwitchElementsType<Then> = PixiVNJsonStepSwitchElementType<Then>[] | PixiVNJsonConditionalStatements<Then[]>;
/**
 * Picks one element at random each time the step is visited.
 */
interface PixiVNJsonRandom<Then> {
    type: "stepswitch";
    choiceType: "random";
    /**
     * The pool of elements to choose from randomly.
     */
    elements: PixiVNJsonStepSwitchElementsType<Then>;
}
/**
 * Picks elements in a random order, advancing through the list across visits (no repeats until exhausted).
 */
interface PixiVNJsonSequentialRandom<Then> {
    type: "stepswitch";
    choiceType: "sequentialrandom";
    /**
     * The pool of elements to iterate through in randomised order.
     */
    elements: PixiVNJsonStepSwitchElementsType<Then>;
    /**
     * When the sequential ends, what should be the value? If undefined, it will return undefined.
     * If "lastItem", it will return the last item in the array.
     */
    end: undefined | "lastItem";
    /**
     * The subId is used for managing nested switches
     */
    nestedId?: string;
}
/**
 * Advances through the elements list one by one on each visit (in order).
 */
interface PixiVNJsonSequential<Then> {
    type: "stepswitch";
    choiceType: "sequential";
    /**
     * The ordered list of elements to iterate through.
     */
    elements: PixiVNJsonStepSwitchElementsType<Then>;
    /**
     * When the sequential ends, what should be the value? If undefined, it will return undefined.
     * If "lastItem", it will return the last item in the array.
     */
    end: undefined | "lastItem";
    /**
     * The subId is used for managing nested switches
     */
    nestedId?: string;
}
/**
 * Loops through the elements list indefinitely, cycling back to the first element after the last.
 */
interface PixiVNJsonLoop<Then> {
    type: "stepswitch";
    choiceType: "loop";
    /**
     * The list of elements to cycle through.
     */
    elements: PixiVNJsonStepSwitchElementsType<Then>;
    /**
     * The subId is used for managing nested switches
     */
    nestedId?: string;
}
/**
 * A step-switch selects one element from a list using a defined strategy (random, sequential, loop, or sequential-random).
 */
type PixiVNJsonStepSwitch<Then> = PixiVNJsonRandom<Then> | PixiVNJsonSequential<Then> | PixiVNJsonLoop<Then> | PixiVNJsonSequentialRandom<Then>;

/**
 * This element is used in case a {@link PixiVNJsonConditionalStatements} gives a result that must be combined with another calculated through other {@link PixiVNJsonConditionalStatements}.
 * in case this possibility is not managed, it will be taken into consideration {@link PixiVNJsonConditionalResultToCombine.firstItem}
 */
type PixiVNJsonConditionalResultToCombine<T> = {
    type: "resulttocombine";
    /**
     * Defines how the two results are combined:
     * - `"cross"` — cartesian product / pairwise combination of both results
     * - `"union"` — concatenation / merge of both results into a single collection
     */
    combine: "cross" | "union";
    /**
     * The first (primary) result item, used as a fallback if the second conditional produces no result.
     */
    firstItem?: T;
    /**
     * The second conditional item(s) whose result will be combined with {@link firstItem}.
     */
    secondConditionalItem?: PixiVNJsonStepSwitchElementType<T>[];
};

/**
 * A conditional statement that evaluates to a value of type `Then`.
 * It can be either:
 * - a {@link PixiVNJsonStepSwitch} — selects a result from a list based on a strategy (random, sequential, loop)
 * - a {@link PixiVNJsonIfElse} — evaluates a condition and returns the matching branch result,
 *   which may itself be another conditional or a {@link PixiVNJsonConditionalResultToCombine}
 */
type PixiVNJsonConditionalStatements<Then> = PixiVNJsonStepSwitch<Then> | PixiVNJsonIfElse<Then | PixiVNJsonConditionalStatements<Then> | PixiVNJsonConditionalResultToCombine<Then>>;

/**
 * Retrieves a value from the persistent storage, flag storage, or temporary storage.
 */
type PixiVNJsonStorageGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * Key of the storage
     */
    key: string;
    /**
     * Type of the storage, if it is a flagStorage or a storage.
     * If it is a flagStorage, the value will be get with the function {@link getFlag}
     */
    storageType: "storage" | "flagStorage" | "tempstorage";
};
type PixiVNJsonParamGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * Index of the parameter in the params array.
     */
    key: number;
    storageType: "params";
};
/**
 * Retrieves the number of times a label has been opened.
 */
type PixiVNJsonLabelGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * Id of the label
     */
    label: string;
    /**
     * If it is a label, the value will be get with the function {@link narration.getTimesLabelOpened}
     */
    storageType: "label";
};
/**
 * Retrieves the number of times a specific choice has been selected.
 */
type PixiVNJsonChoiceGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * index of the choice
     */
    index: number;
    /**
     * If it is a choice, the value will be get with the function {@link narration.getTimesChoiceOpened}
     */
    storageType: "choice";
};
/**
 * Retrieves a value from the logic/arithmetic layer (result of a computation or condition).
 */
type PixiVNJsonLogicGet = {
    type: "value";
    storageOperationType: "get";
    /**
     * The arithmetic or conditional operation whose result is the retrieved value.
     */
    operation: PixiVNJsonArithmeticOperations | PixiVNJsonConditions;
    storageType: "logic";
};
/**
 * Union of all "get value" operations — reads from storage, params, labels, choices, or a logic expression.
 */
type PixiVNJsonValueGet = PixiVNJsonStorageGet | PixiVNJsonParamGet | PixiVNJsonLabelGet | PixiVNJsonChoiceGet | PixiVNJsonLogicGet | PixiVNJsonFunction;
/**
 * Invokes a named function and returns its result.
 * Functions are registered in the Pixi'VN runtime and can receive typed arguments.
 */
type PixiVNJsonFunction = {
    type: "function";
    /**
     * The name of the registered function to call.
     */
    functionName: string;
    /**
     * Arguments to pass to the function. Each argument can be a condition, a raw value,
     * a value-get operation, or an arithmetic expression.
     */
    args: (PixiVNJsonConditions | StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations)[];
};
/**
 * Sets a value in either the persistent storage or the temporary (session) storage.
 */
type PixiVNJsonOnlyStorageSet = {
    type: "value";
    storageOperationType: "set";
    /**
     * Key of the storage
     */
    key: string;
    /**
     * Value to be set in the storage
     */
    value: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType>;
    /**
     * Type of the storage, if it is a flagStorage or a storage.
     */
    storageType: "storage" | "tempstorage";
};
/**
 * Sets a positional parameter value in the params temporary storage.
 */
type PixiVNJsonOnlyParamSet = {
    type: "value";
    storageOperationType: "set";
    /**
     * Index of the parameter in the params array to set.
     */
    key: number;
    /**
     * Value to be set at the given param index.
     */
    value: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType>;
    storageType: "params";
};
/**
 * Sets a boolean flag in the flag storage.
 * Flag storage is a dedicated boolean key-value store queried with {@link getFlag}.
 */
type PixiVNJsonFlagSet = {
    type: "value";
    storageOperationType: "set";
    /**
     * Key of the storage
     */
    key: string;
    /**
     * Value to be set in the storage
     */
    value: boolean;
    /**
     * Type of the storage, if it is a flagStorage or a storage.
     */
    storageType: "flagStorage";
};
/**
 * Union of all "set value" operations — writes to storage, flag storage, or params.
 */
type PixiVNJsonValueSet = PixiVNJsonOnlyStorageSet | PixiVNJsonFlagSet | PixiVNJsonOnlyParamSet;

/**
 * Binary arithmetic operation between two values (left OP right).
 */
interface PixiVNJsonArithmeticOperationsArithmetic {
    type: "arithmetic";
    /**
     * Left value of the arithmetic operation
     */
    leftValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations>;
    /**
     * Right value of the arithmetic operation
     */
    rightValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations>;
    /**
     * Operator of the arithmetic operation:
     * - `"*"` multiplication
     * - `"/"` division
     * - `"+"` addition (concatenation for strings and arrays)
     * - `"-"` subtraction (removal of elements for arrays)
     * - `"%"` modulo
     * - `"POW"` exponentiation
     * - `"RANDOM"` random integer between leftValue and rightValue (inclusive)
     * - `"INTERSECTION"` intersection of two arrays (only elements present in both arrays are included in the result)
     */
    operator: "*" | "/" | "+" | "-" | "%" | "POW" | "RANDOM" | "INTERSECTION";
}
/**
 * Unary arithmetic operation applied to a single value (e.g. INT, FLOOR, FLOAT).
 */
interface PixiVNJsonArithmeticOperationsArithmeticSingle {
    type: "arithmeticsingle";
    /**
     * Left value of the arithmetic operation
     */
    leftValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations | PixiVNJsonConditionalStatements<StorageElementType | PixiVNJsonValueGet | PixiVNJsonArithmeticOperations>;
    /**
     * Operator of the arithmetic operation:
     * - `"INT"` truncates the value to an integer (removes the decimal part)
     * - `"FLOOR"` rounds down to the nearest integer
     * - `"FLOAT"` converts the value to a floating-point number
     */
    operator: "INT" | "FLOOR" | "FLOAT";
}
/**
 * Arithmetic operations for the PixiVNJson
 */
type PixiVNJsonArithmeticOperations = PixiVNJsonArithmeticOperationsArithmeticSingle | PixiVNJsonArithmeticOperationsArithmetic;

/**
 * Combines multiple conditions with a logical AND or OR.
 */
type PixiVNJsonUnionConditionAndOr = {
    type: "union";
    /**
     * The list of conditions to combine.
     */
    conditions: PixiVNJsonConditions[];
    /**
     * - `"and"` — all conditions must be true
     * - `"or"` — at least one condition must be true
     */
    unionType: "and" | "or";
};
/**
 * Negates a single condition with a logical NOT.
 */
type PixiVNJsonUnionConditionNot = {
    type: "union";
    /**
     * The condition to negate.
     */
    condition: PixiVNJsonConditions;
    unionType: "not";
};
/**
 * Union of AND/OR and NOT logical operators over conditions.
 */
type PixiVNJsonUnionCondition = PixiVNJsonUnionConditionAndOr | PixiVNJsonUnionConditionNot;

/**
 * Supported comparison operators.
 * - `"=="` equal
 * - `"!="` not equal
 * - `"<"` less than
 * - `"<="` less than or equal
 * - `">"` greater than
 * - `">="` greater than or equal
 * - `"CONTAINS"` checks whether the left string/array contains the right value, if left and right are arrays, checks if all items in right are included in left
 */
type PixiVNJsonComparationOperatorsType = "==" | "!=" | "<" | "<=" | ">" | ">=" | "CONTAINS";
/**
 * Comparation for PixiVNJson.
 * In this comparation, the values to be converted to string and compared.
 */
type PixiVNJsonComparation = {
    type: "compare";
    /**
     * Left value of the comparation
     */
    leftValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonConditions;
    /**
     * Right value of the comparation
     */
    rightValue: StorageElementType | PixiVNJsonValueGet | PixiVNJsonConditions;
    /**
     * Operator of the comparation
     */
    operator: PixiVNJsonComparationOperatorsType;
};
/**
 * A plain value condition — truthy/falsy evaluation of a raw value or a value-get result.
 */
type PixiVNJsonValueCondition = StorageElementType | PixiVNJsonValueGet;
/**
 * Union of all condition types supported by PixiVNJson:
 * - {@link PixiVNJsonComparation} — binary comparison between two values
 * - {@link PixiVNJsonValueCondition} — truthy/falsy check on a plain value
 * - {@link PixiVNJsonUnionCondition} — logical AND, OR, or NOT of other conditions
 * - {@link PixiVNJsonArithmeticOperations} — arithmetic result used as a boolean (non-zero = true)
 */
type PixiVNJsonConditions = PixiVNJsonComparation | PixiVNJsonValueCondition | PixiVNJsonUnionCondition | PixiVNJsonArithmeticOperations;

/**
 * If-Else condition for PixiVNJson
 */
interface PixiVNJsonIfElse<Then> {
    type: "ifelse";
    /**
     * The list of conditions to be checked.
     *
     * if is a {@link StorageElementType} or a {@link PixiVNJsonValueGet}:
     * - if is a array or object, the condition is true if not empty
     * - if is a string, the condition is true if not empty
     * - if is a number, the condition is true if not zero
     * - if is a boolean, the condition is true if true
     * - if is null or undefined, the condition is false
     */
    condition: PixiVNJsonConditions;
    /**
     * The value to be returned if the condition is true.
     */
    then: Then | PixiVNJsonIfElse<Then>;
    /**
     * The value to be returned if the condition is false.
     */
    else?: Then | PixiVNJsonIfElse<Then>;
}

/**
 * Animates one or more canvas elements simultaneously using keyframe-based animation.
 */
type PixiVNJsonAnimateBase<T extends CanvasBaseInterface<any>> = {
    type: "animate";
    /**
     * Alias (or list of aliases) of the canvas elements to animate.
     */
    alias: string | string[];
    /**
     * The keyframes that define the animation values over time.
     */
    keyframes: KeyframesType<T>;
    /**
     * Additional options controlling the animation (duration, easing, repeat, etc.).
     */
    options?: AnimationOptions;
    /**
     * Pixi.js update priority for this animation ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Animates a canvas element using a sequence of segments (timeline-based animation).
 */
type PixiVNJsonAnimateSequence<T extends CanvasBaseInterface<any>> = {
    type: "animate-sequence";
    /**
     * Alias of the canvas element to animate.
     */
    alias: string;
    /**
     * Ordered list of animation segments, each optionally including a transition.
     */
    sequence: (ObjectSegment<T> | ObjectSegmentWithTransition<T>)[];
    /**
     * Additional options controlling the sequence playback.
     */
    options?: SequenceOptions;
    /**
     * Pixi.js update priority for this animation ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Union of all canvas animation operations — keyframe-based or sequence-based.
 */
type PixiVNJsonCanvasAnimate<T extends CanvasBaseInterface<any> = ImageSprite> = PixiVNJsonAnimateBase<T> | PixiVNJsonAnimateSequence<T>;

/**
 * Applies a shake effect to a canvas element.
 */
type PixiVNJsonEffectShake = {
    type: "shake";
    /**
     * Alias of the canvas element to apply the shake effect to.
     */
    alias: string;
    /**
     * Configuration properties for the shake effect (amplitude, duration, etc.).
     */
    props: ShakeEffectProps;
    /**
     * Pixi.js update priority for the effect ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Union of all canvas visual effects.
 */
type PixiVNJsonCanvasEffect = PixiVNJsonEffectShake;

/**
 * Cross-dissolve transition — blends the element in or out by gradually changing its opacity.
 */
type DissolveTransition = {
    type: "dissolve";
    /**
     * Configuration options for the dissolve transition.
     */
    props?: ShowWithDissolveTransitionProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Fade transition — fades the element in or out by animating its alpha value.
 */
type FadeTransition = {
    type: "fade";
    /**
     * Configuration options for the fade transition.
     */
    props?: ShowWithFadeTransitionProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Move-in / Move-out transition — slides the element into or out of the viewport.
 */
type MoveInOutTransition = {
    type: "movein" | "moveout";
    /**
     * Configuration options for the move transition (direction, duration, easing, etc.).
     */
    props?: MoveInOutProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Zoom-in / Zoom-out transition — scales the element into or out of view.
 */
type ZoomInOutTransition = {
    type: "zoomin" | "zoomout";
    /**
     * Configuration options for the zoom transition (scale, duration, easing, etc.).
     */
    props?: ZoomInOutProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Push-in / Push-out transition — pushes the element onto or off the viewport, displacing the current content.
 */
type PushInOutTransition = {
    type: "pushin" | "pushout";
    /**
     * Configuration options for the push transition (direction, duration, easing, etc.).
     */
    props?: PushInOutProps;
    /**
     * Pixi.js update priority for the transition ticker callback.
     */
    priority?: UPDATE_PRIORITY;
};
/**
 * Union of all supported canvas media transitions.
 */
type PixiVNJsonMediaTransiotions = DissolveTransition | FadeTransition | MoveInOutTransition | ZoomInOutTransition | PushInOutTransition;

/**
 * Shows an image or video asset on the canvas.
 */
type PixiVNJsonCanvasImageVideoShow = {
    type: "image" | "video";
    operationType: "show";
    /**
     * Unique identifier (alias) used to reference this element on the canvas.
     */
    alias: string;
    /**
     * The url of the image or video.
     * If the url is not provided, the url will be set to the alias.
     */
    url?: string;
    /**
     * Display options (position, scale, alpha, etc.) for the image or video sprite.
     */
    props?: ImageSpriteOptions;
    /**
     * Optional transition effect applied when the element appears on screen.
     */
    transition?: PixiVNJsonMediaTransiotions;
};
/**
 * Shows an image container (a group of layered images) on the canvas.
 */
type PixiVNJsonCanvasImageContainerShow = {
    type: "imagecontainer";
    operationType: "show";
    /**
     * Unique identifier (alias) used to reference this element on the canvas.
     */
    alias: string;
    /**
     * The ordered list of image URLs that compose the container layers.
     */
    urls: string[];
    /**
     * Display options for the image container.
     */
    props?: ImageContainerOptions<ImageSprite>;
    /**
     * Optional transition effect applied when the element appears on screen.
     */
    transition?: PixiVNJsonMediaTransiotions;
};
/**
 * Shows a text element on the canvas.
 */
type PixiVNJsonCanvasTextShow = {
    type: "text";
    operationType: "show";
    /**
     * Unique identifier (alias) used to reference this element on the canvas.
     */
    alias: string;
    /**
     * The string content to display.
     */
    text: string;
    /**
     * Display options (font, style, position, etc.) for the text element.
     */
    props?: TextOptions;
    /**
     * Optional transition effect applied when the element appears on screen.
     */
    transition?: PixiVNJsonMediaTransiotions;
};
/**
 * Edits the properties of an existing image sprite on the canvas.
 */
type PixiVNJsonImageEdit = {
    type: "image";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial memory/state properties to update on the image sprite.
     */
    props?: Partial<ImageSpriteMemory>;
};
/**
 * Edits the properties of an existing video sprite on the canvas.
 */
type PixiVNJsonVideoEdit = {
    type: "video";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial memory/state properties to update on the video sprite.
     */
    props?: Partial<VideoSpriteMemory>;
};
/**
 * Edits the properties of an existing image container on the canvas.
 */
type PixiVNJsonImageContainerEdit = {
    type: "imagecontainer";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial memory/state properties to update on the image container.
     */
    props?: Partial<ImageContainerMemory>;
};
/**
 * Edits the properties of an existing text element on the canvas.
 */
type PixiVNJsonTextEdit = {
    type: "text";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial memory/state properties to update on the text element.
     */
    props?: Partial<TextMemory>;
};
/**
 * Edits the properties of an unknown/generic canvas element.
 * Use this when the specific element type is not one of the built-in kinds.
 */
type PixiVNJsonUnknownEdit<T extends ContainerOptions<any>> = {
    type: "canvaselement";
    operationType: "edit";
    /**
     * Alias of the canvas element to edit.
     */
    alias: string;
    /**
     * Partial options/properties to update on the canvas element.
     */
    props?: Partial<T>;
};
/**
 * Removes a canvas element from the stage, optionally with a transition.
 */
type PixiVNJsonCanvasRemove = {
    type: "image" | "video" | "imagecontainer" | "canvaselement" | "text";
    operationType: "remove";
    /**
     * Alias of the canvas element to remove.
     */
    alias: string;
    /**
     * Optional transition effect applied while the element disappears.
     */
    transition?: PixiVNJsonMediaTransiotions;
};
/**
 * Pauses or resumes playback of a video sprite on the canvas.
 */
type PixiVNJsonVideoPauseResume = {
    type: "video";
    operationType: "pause" | "resume";
    /**
     * Alias of the video element to pause or resume.
     */
    alias: string;
};
/**
 * Loads or lazy-loads asset bundles or individual assets into memory.
 */
type PixiVNJsonAssetsLoad = {
    type: "assets" | "bundle";
    operationType: "load" | "lazyload";
    /**
     * List of asset aliases (or bundle names) to load.
     */
    aliases: string[];
};
type PixiVNJsonCanvasShow = PixiVNJsonCanvasImageContainerShow | PixiVNJsonCanvasImageVideoShow | PixiVNJsonCanvasTextShow;
/**
 * Union of all canvas-element edit operations.
 */
type PixiVNJsonCanvasEdit = PixiVNJsonImageEdit | PixiVNJsonVideoEdit | PixiVNJsonImageContainerEdit | PixiVNJsonTextEdit | PixiVNJsonUnknownEdit<ImageSpriteMemory | VideoSpriteMemory | ContainerMemory | TextMemory>;
/**
 * Union of all canvas operations — show, edit, remove, animate, apply effects, and asset loading.
 */
type PixiVNJsonCanvas = PixiVNJsonCanvasShow | PixiVNJsonCanvasEdit | PixiVNJsonCanvasRemove | PixiVNJsonVideoPauseResume | PixiVNJsonAssetsLoad | PixiVNJsonCanvasAnimate | PixiVNJsonCanvasEffect;

/**
 * Requests user input during the narrative.
 * When this operation is encountered, the engine pauses and waits for the player to provide a value.
 */
type PixiVNJsonInputRequest = {
    type: "input";
    operationType: "request";
    /**
     * The expected value type for the input (e.g. `"string"`, `"number"`, `"boolean"`).
     * Used by the engine to validate or cast the player's answer.
     */
    valueType?: string;
    /**
     * A default value that will be used if the player does not provide any input.
     */
    defaultValue?: any;
};
/**
 * Clears (resets) the current dialogue state.
 * This is typically used to wipe any displayed text before showing new content.
 */
type PixiVNJsonDialogue = {
    type: "dialogue";
    operationType: "clean";
};
/**
 * Narration operation — either a dialogue clear or a user-input request.
 */
type PixiVNJsonNarration = PixiVNJsonDialogue | PixiVNJsonInputRequest;

/**
 * Starts playback of a sound asset.
 */
type PixiVNJsonSoundPlay = {
    type: "sound";
    operationType: "play";
    /**
     * Unique identifier (alias) used to reference this sound.
     */
    alias: string;
    /**
     * URL of the sound file. If omitted, the alias is used as the URL.
     */
    url?: string;
    /**
     * Playback options such as volume, loop, channel, and start offset.
     */
    props?: SoundPlayOptionsWithChannel;
};
/**
 * Stops a playing sound and removes it from the audio context.
 */
type PixiVNJsonSoundRemove = {
    type: "sound";
    operationType: "stop";
    /**
     * Alias of the sound to stop.
     */
    alias: string;
};
/**
 * Pauses or resumes a sound, a channel, or all audio.
 */
type PixiVNJsonSoundPauseResume = {
    type: "sound" | "channel";
    operationType: "pause" | "resume";
    /**
     * Alias of the sound or channel to pause/resume.
     */
    alias: string;
} | {
    type: "all";
    operationType: "pause" | "resume" | "stop";
};
/**
 * Edits the properties of a currently playing sound (volume, speed, muted, loop, etc.).
 */
type PixiVNJsonSoundEdit = {
    type: "sound";
    operationType: "edit";
    /**
     * Alias of the sound to edit.
     */
    alias: string;
    /**
     * Partial set of properties to apply to the sound.
     */
    props: Partial<Pick<MediaInterface, "speed" | "muted" | "loop" | "paused"> & Pick<SoundPlayOptionsWithChannel, "volume">>;
};
/**
 * Union of all sound operations — play, stop, pause/resume, and edit.
 */
type PixiVNJsonSound = PixiVNJsonSoundPlay | PixiVNJsonSoundRemove | PixiVNJsonSoundPauseResume | PixiVNJsonSoundEdit;

/**
 * An operation string that holds a list of string/value fragments to be concatenated at runtime.
 * Used internally to represent string interpolation expressions before they are fully resolved.
 */
type PixiVNJsonOperationString = {
    type: "operationtoconvert";
    /**
     * The ordered list of string fragments and/or value-get expressions to concatenate.
     */
    values: (string | PixiVNJsonValueGet | PixiVNJsonConditionalStatements<string | PixiVNJsonValueGet>)[];
};
/**
 * A single resolved operation — a value set, canvas operation, sound operation,
 * narration operation, or function call — optionally annotated with an origin string.
 */
type PixiVNJsonOperation = (PixiVNJsonValueSet | PixiVNJsonCanvas | PixiVNJsonSound | PixiVNJsonNarration | PixiVNJsonFunction) & {
    /**
     * This value is used by the system to know where this operation is from, for example, if is generated from a string operation.
     */
    $origin?: string;
};
/**
 * A conditional operation — either a plain operation, an if-else that resolves to one,
 * or an operation-string (string interpolation expression).
 */
type PixiVNJsonConditionalOperation = PixiVNJsonOperation | PixiVNJsonIfElse<PixiVNJsonOperation> | PixiVNJsonOperationString;

/**
 * A player-presentable choice in a menu.
 */
type PixiVNJsonChoice = {
    /**
     * The text to be displayed.
     */
    text: PixiVNJsonDialogText;
    /**
     * The label id to be opened.
     */
    label: string;
    /**
     * Label opening mode
     */
    type: LabelRunModeType;
    /**
     * The properties to be passed to the label.
     */
    props: StorageObjectType;
    /**
     * If this is true, the choice can only be made once.
     */
    oneTime?: boolean;
    /**
     * If this is true, the choice can see only if there are no other choices. For example, all choices are one-time choices and they are already selected.
     */
    onlyHaveNoChoice?: boolean;
    /**
     * If this is true and if is the only choice, it will be automatically selected, and call/jump to the label.
     */
    autoSelect?: boolean;
};
/**
 * A list of choices (possibly conditional) that are shown to the player as a menu.
 */
type PixiVNJsonChoices = (PixiVNJsonChoice | PixiVNJsonConditionalStatements<PixiVNJsonChoice>)[];
/**
 * The text content of a dialogue line.
 * Can be a plain string, a dynamic value-get, a conditional expression, or an array of any of these
 * (which will be concatenated into a single string at runtime).
 */
type PixiVNJsonDialogText = string | PixiVNJsonValueGet | PixiVNJsonConditionalStatements<string | PixiVNJsonValueGet | string[]> | (string | PixiVNJsonValueGet | PixiVNJsonConditionalStatements<string | PixiVNJsonValueGet | string[]>)[];
/**
 * A dialogue line, optionally attributed to a character.
 * When a plain `Text` value is used, no character attribution is included.
 */
type PixiVNJsonDialog<Text = string> = {
    /**
     * The character id that will speak.
     */
    character: string;
    /**
     * The text to be displayed.
     */
    text: Text;
} | Text;
/**
 * Describes a label that should be opened (called or jumped to) during a step.
 */
type PixiVNJsonLabelToOpen<T extends {} = object> = {
    /**
     * The id of the label to open.
     */
    label: string | PixiVNJsonValueGet;
    /**
     * Label opening mode
     */
    type: LabelRunModeType;
    /**
     * The properties to be passed to the label. if you don't want to pass a object, but a list of parameters, you can use the {@link PixiVNJsonLabelToOpen.params} attribute.
     */
    props?: StepLabelPropsType<T>;
    /**
     * **It is not recommended to use it, use it only if necessary**. The parameters to be passed to the label. If you want to pass an object, use the {@link PixiVNJsonLabelToOpen.props} attribute.
     * "params" attribute will be stored in the temp storage with the key: {@link PIXIVNJSON_PARAM_ID} + ({@link narration.openedLabels.length} - 1).
     */
    params?: unknown[];
};
/**
 * Steps of a label.
 * Order of operations:
 * 1. run all {@link PixiVNJsonLabelStep.operations}
 * 2. set {@link PixiVNJsonLabelStep.choices}, {@link PixiVNJsonLabelStep.dialogue}, {@link PixiVNJsonLabelStep.glueEnabled}
 * 3. open {@link PixiVNJsonLabelStep.labelToOpen}
 * 4. go to next step if {@link PixiVNJsonLabelStep.goNextStep} is true
 * 5. end the label if {@link PixiVNJsonLabelStep.end} is "label_end"
 */
type PixiVNJsonLabelStep = {
    /**
     * Operations to execute at the start of this step (storage writes, canvas updates, sound, etc.).
     */
    operations?: PixiVNJsonConditionalOperation[];
    /**
     * Variable used to display a choice menu.
     */
    choices?: PixiVNJsonChoices | PixiVNJsonConditionalStatements<PixiVNJsonChoices>;
    /**
     * Variable used to display a dialog.
     */
    dialogue?: PixiVNJsonDialog<PixiVNJsonDialogText> | PixiVNJsonConditionalStatements<PixiVNJsonDialog<PixiVNJsonDialogText>>;
    /**
     * This variable is used to add the next dialog text into the current dialog memory.
     * This value was added to introduce Ink Glue functionality https://github.com/inkle/ink/blob/master/Documentation/WritingWithInk.md#glue
     */
    glueEnabled?: boolean | PixiVNJsonConditionalStatements<boolean>;
    /**
     * Variable used to open a label.
     */
    labelToOpen?: PixiVNJsonLabelToOpen | PixiVNJsonConditionalStatements<PixiVNJsonLabelToOpen> | (PixiVNJsonLabelToOpen | PixiVNJsonConditionalStatements<PixiVNJsonLabelToOpen>)[];
    /**
     * If is true, the next step will be executed automatically.
     */
    goNextStep?: boolean | PixiVNJsonConditionalStatements<boolean>;
    /**
     * Variable used to end some elements of the narrative.
     * - game_end: ends the game
     * - label_end: ends the label
     */
    end?: "game_end" | "label_end" | PixiVNJsonConditionalStatements<"game_end" | "label_end">;
    /**
     * If set, this step is replaced by the result of evaluating the given conditional statement.
     * Allows an entire step to be chosen at runtime based on a condition or step-switch strategy.
     */
    conditionalStep?: PixiVNJsonConditionalStatements<PixiVNJsonLabelStep | PixiVNJsonLabelStep[]>;
};

/**
 * Collection of labels to be used in the narrative.
 */
type PixiVNJsonLabels = {
    [labelId: string]: PixiVNJsonLabelStep[];
};

/**
 * PixiVNJson It can be defined as a programming language to write a narrative written in json.
 */
interface PixiVNJson {
    /**
     * The URI of the JSON Schema that describes and validates this document.
     *
     * You can point to a specific version of the schema, for example:
     * - `"https://pixi-vn.web.app/schemas/1.13.0/schema.json"` — pin to a specific version
     * - `"https://pixi-vn.web.app/schemas/latest/schema.json"` — always use the latest version
     *
     * Most editors (VS Code, WebStorm, etc.) use this field to provide
     * auto-completion, hover documentation, and validation for the document.
     */
    $schema?: string;
    /**
     * The operations to be executed before the narrative starts.
     * For the set storage: They will be set only if there are no variables with the same key already.
     * For the det tempstorage: if there are variables with the same key already, they will be overwritten.
     */
    initialOperations?: (PixiVNJsonValueSet | PixiVNJsonIfElse<PixiVNJsonValueSet>)[];
    /**
     * The labels to be used in the narrative. They will be added to the system
     */
    labels?: PixiVNJsonLabels;
}

/**
 * Internal storage key prefix used to pass positional parameters to a called label.
 * The full key is `PIXIVNJSON_PARAM_ID + <label-depth-index>`.
 *
 * @internal
 */
declare const PIXIVNJSON_PARAM_ID = "___param___";
/**
 * The URL of the JSON Schema for the current version of pixi-vn-json.
 *
 * You can use this constant as the value of the `$schema` field in your PixiVNJson documents
 * so that editors can validate and auto-complete the document.
 *
 * Example:
 * ```json
 * {
 *   "$schema": "https://pixi-vn.web.app/schemas/1.13.0/schema.json"
 * }
 * ```
 */
declare const PIXIVNJSON_SCHEMA_URL: string;
/**
 * All comparison operators supported by {@link PixiVNJsonConditions} expressions.
 */
declare const PixiVNJsonComparationOperators: PixiVNJsonComparationOperatorsType[];

/**
 * A handler function invoked for each `[key]` token found in the text that passes the
 * {@link ReplaceHandlerOptions.validation} check.
 *
 * @param key The content found inside the square brackets (without the brackets themselves).
 *   For example, for the token `[john]` the key is `"john"`.
 * @returns The string to substitute in place of `[key]`, or `undefined` to leave the token unchanged.
 */
type ReplaceHandler = (
/**
 * The key to be replaced
 */
key: string) => string | undefined;
/**
 * Configuration options for a text-replacement handler registered via {@link TextReplaces.add}.
 */
type ReplaceHandlerOptions = {
    /**
     * A unique name that identifies this handler.
     * Used for documentation and debugging purposes.
     */
    name: string;
    /**
     * An optional human-readable description of what this handler does.
     * Used for documentation purposes.
     */
    description?: string;
    /**
     * Determines whether this handler should be invoked for a given `[key]` token.
     *
     * - `"all"` – the handler is always invoked for every token found.
     * - `"characterId"` – the handler is invoked only when the key matches a registered character ID
     *   (i.e. the character is present in `RegisteredCharacters`).
     * - `RegExp` – the key string is tested against the regular expression. The handler is invoked
     *   only if the regex matches.
     * - `ZodType<string>` – the key string is validated with `schema.safeParse(key)`. The handler
     *   is invoked only if validation succeeds.
     *
     * @example
     * ```ts
     * // RegExp: only replace keys that look like lowercase identifiers
     * validation: /^[a-z_]+$/
     *
     * // Zod: only replace keys that are one of a fixed set of values
     * import { z } from "zod"
     * validation: z.enum(["player", "npc", "enemy"])
     * ```
     */
    validation: RegExp | "characterId" | "all" | ZodType<string>;
    /**
     * When this handler should be invoked relative to the translation step.
     *
     * - `"before-translation"` – the handler runs **before** {@link onInkTranslate} is called.
     *   Useful for pre-processing tokens, e.g. converting `[key]` into `{{key}}` for i18next.
     * - `"after-translation"` – the handler runs **after** {@link onInkTranslate} is called.
     *   Useful for substituting values that depend on the translated text.
     *
     * @default "before-translation"
     */
    type?: "after-translation" | "before-translation";
};

/**
 * A middleware handler that can intercept and transform a logic value before it is
 * returned by {@link VariableGetter.getLogichValue}.
 *
 * Handlers are called in registration order, each receiving the current value and a
 * `next` function to invoke the rest of the chain (including the built-in resolver).
 * Return `undefined` to fall through to `next`.
 */
type VariableGetterHandler = <T = StorageElementType>(value: T, next: (value: T) => T | undefined) => T | undefined;

/**
 * Manages text replacement handlers that process content enclosed in square brackets (`[key]`).
 *
 * Handlers are called in the order they were added. For each handler, the current text is scanned
 * for all `[key]` patterns. If the handler's `validation` matches a key, the handler is
 * invoked with that key. If the handler returns a string, all occurrences of `[key]` are replaced
 * with the returned value. After a handler finishes processing the text, the next handler starts
 * on the updated text.
 *
 * Each handler specifies whether it runs before or after translation via the `type` field in its
 * options (defaults to `"before-translation"`).
 *
 * @example
 * ```ts
 * import { TextReplaces } from 'pixi-vn-ink'
 * import { getCharacterById } from "@drincs/pixi-vn";
 *
 * // Replace [characterId] with the character's display name
 * TextReplaces.add(
 *     (key) => {
 *         const character = getCharacterById(key)
 *         return character?.name
 *     },
 *     {
 *         name: "character-name",
 *         description: "Replaces character IDs with their display names",
 *         validation: /^[a-z_]+$/,
 *         type: "after-translation",
 *     }
 * )
 * // "Hello [john], meet [jane]!" -> "Hello John, meet Jane!"
 * ```
 */
declare namespace TextReplaces {
    /**
     * Configuration options for the `TextReplaces` system.
     */
    const options: {
        /**
         * The regex used to find replacement tokens in the text (e.g. `[key]`).
         * @default /\[([^\]]+)\]/
         */
        replaceRegex: RegExp;
    };
    /**
     * Registers a new replacement handler.
     *
     * Handlers are executed in the order they are added. The first handler added runs first.
     *
     * When the first handler of a given type (`"before-translation"` or `"after-translation"`)
     * is registered, the corresponding translator hook (`translator.beforeToTranslate` or
     * `translator.afterToTranslate`) is automatically set so that `TextReplaces` takes exclusive
     * ownership of that hook. Do **not** mix `TextReplaces` with the deprecated
     * {@link onReplaceTextBeforeTranslation} / {@link onReplaceTextAfterTranslation} functions
     * for the same phase, as they will overwrite each other's hook.
     *
     * @param fn The handler function. Receives the key found inside `[...]` and should return
     *   the replacement string, or `undefined` to leave that token unchanged.
     * @param handlerOptions Configuration for this handler, including its name, optional
     *   description, validation regex, and execution phase.
     * @example
     * ```ts
     * import { TextReplaces } from 'pixi-vn-ink'
     *
     * TextReplaces.add(
     *     (key) => key === "player" ? "Mario" : undefined,
     *     {
     *         name: "player-name",
     *         validation: /^player$/,
     *     }
     * )
     * ```
     */
    function add(fn: ReplaceHandler, handlerOptions: ReplaceHandlerOptions): void;
    /**
     * Removes a previously registered handler function.
     *
     * Only the first registration matching `fn` is removed. If the same function was added
     * multiple times, subsequent registrations remain.
     *
     * @param fn The handler function to remove.
     */
    function remove(fn: ReplaceHandler): void;
    /**
     * Returns metadata for all registered handlers, in registration order.
     *
     * @returns An array of {@link ReplaceHandlerOptions} for each registered handler.
     */
    function info(): ReplaceHandlerOptions[];
    /**
     * Applies all registered handlers of the specified type to the given text in order.
     *
     * For each handler:
     * 1. All `[key]` tokens currently present in the text are collected.
     * 2. For each unique key, the handler's `validation` is tested against the key.
     * 3. If validation passes, the handler is called with the key.
     * 4. If the handler returns a string, **all** occurrences of `[key]` in the text are
     *    replaced with that string.
     * 5. After the handler has processed all tokens, the next handler starts on the updated text.
     *
     * @param text The source text to process.
     * @param replaceOptions Specifies which phase of handlers to run.
     * @returns The text after all matching handlers have been applied.
     * @example
     * ```ts
     * // Given handlers that replace [name] -> "Mario" and [surname] -> "Rossi":
     * TextReplaces.replace("Ciao [name] [surname]. [name] vai pure", { type: "before-translation" })
     * // => "Ciao Mario Rossi. Mario vai pure"
     * ```
     */
    function replace(text: string, replaceOptions: {
        /** Which phase of handlers to execute. */
        type: "after-translation" | "before-translation";
    }): string;
}

declare namespace VariableGetter {
    /**
     * Registers a new middleware handler into the resolution chain.
     * Handlers are invoked in the order they were added.
     *
     * @param handler - The middleware handler to register.
     */
    function add(handler: VariableGetterHandler): void;
    /**
     * Removes all registered middleware handlers, restoring the default resolution behaviour.
     */
    function clear(): void;
    /**
     * Resolves a JSON logic value, running it through all registered middleware handlers
     * before falling back to the built-in storage/arithmetic/condition evaluator.
     *
     * @param value - The value or logic expression to resolve.
     * @param props - The current step label props passed to each handler.
     * @returns The resolved value, or `undefined`.
     */
    function getLogichValue<T = StorageElementType>(value: any, props?: StepLabelPropsType): T | undefined;
}

/**
 * Initialises the pixi-vn-json system by registering all default operation handlers
 * (canvas, sound, assets, storage, narration, etc.) into the {@link JsonUnifier}.
 *
 * Call this function once at application startup, before importing any JSON labels.
 */
declare function init(): void;

export { PIXIVNJSON_PARAM_ID, PIXIVNJSON_SCHEMA_URL, type PixiVNJson, type PixiVNJsonAnimateBase, type PixiVNJsonAnimateSequence, type PixiVNJsonArithmeticOperations, type PixiVNJsonArithmeticOperationsArithmetic, type PixiVNJsonArithmeticOperationsArithmeticSingle, type PixiVNJsonCanvas, type PixiVNJsonCanvasAnimate, type PixiVNJsonCanvasEdit, type PixiVNJsonCanvasEffect, type PixiVNJsonCanvasImageContainerShow, type PixiVNJsonCanvasImageVideoShow, type PixiVNJsonCanvasRemove, type PixiVNJsonCanvasShow, type PixiVNJsonCanvasTextShow, type PixiVNJsonChoice, type PixiVNJsonChoiceGet, type PixiVNJsonChoices, type PixiVNJsonComparation, PixiVNJsonComparationOperators, type PixiVNJsonComparationOperatorsType, type PixiVNJsonConditionalOperation, type PixiVNJsonConditionalResultToCombine, type PixiVNJsonConditionalStatements, type PixiVNJsonConditions, type PixiVNJsonDialog, type PixiVNJsonDialogText, type PixiVNJsonDialogue, type PixiVNJsonFunction, type PixiVNJsonIfElse, type PixiVNJsonImageContainerEdit, type PixiVNJsonImageEdit, type PixiVNJsonInputRequest, type PixiVNJsonLabelGet, type PixiVNJsonLabelStep, type PixiVNJsonLabelToOpen, type PixiVNJsonLabels, type PixiVNJsonLogicGet, type PixiVNJsonMediaTransiotions, type PixiVNJsonNarration, type PixiVNJsonOnlyStorageSet, type PixiVNJsonOperation, type PixiVNJsonOperationString, type PixiVNJsonParamGet, type PixiVNJsonSound, type PixiVNJsonSoundEdit, type PixiVNJsonSoundPauseResume, type PixiVNJsonSoundPlay, type PixiVNJsonSoundRemove, type PixiVNJsonStepSwitch, type PixiVNJsonStepSwitchElementType, type PixiVNJsonStepSwitchElementsType, type PixiVNJsonStorageGet, type PixiVNJsonTextEdit, type PixiVNJsonUnionCondition, type PixiVNJsonUnknownEdit, type PixiVNJsonValueGet, type PixiVNJsonValueSet, type PixiVNJsonVideoEdit, type PixiVNJsonVideoPauseResume, type ReplaceHandler, type ReplaceHandlerOptions, TextReplaces, VariableGetter, type VariableGetterHandler, init };