---@meta
--- COMMON RUNTIME TYPES SECTION.
--- Source of truth: tool/lua_runtime_defs_common.lua
--- After editing this common section, run:
---   dart run tool/generate_lua_runtime_defs.dart


---@alias RuntimeNodeType
---| 'panel'
---| 'button'
---| 'text'
---| 'circle'
---| 'rect'
---| 'line'
---| 'progress'
---| 'listView'
---| 'sprite'
---| 'image'
---| 'spine'
---| 'particle'

---@alias RuntimeAnchor
---| 'center'
---| 'topLeft'
---| 'topRight'
---| 'bottomLeft'
---| 'bottomRight'

---@alias RuntimeTextAlign
---| 'left'
---| 'center'
---| 'right'

---@alias RuntimeParticlePreset
---| 'burst'
---| 'trail'
---| 'snow'
---| 'confetti'

---@alias RuntimeCommandType
---| 'move_path'
---| 'move_to'
---| 'fade_to'
---| 'scale_to'
---| 'rotate_to'
---| 'remove_node'
---| 'sequence'
---| 'parallel'
---| 'delay'
---| 'toast'
---| 'play_sound'
---| 'play_bgm'
---| 'pause_bgm'
---| 'resume_bgm'
---| 'stop_bgm'
---| 'preload_resources'
---| 'evict_resources'
---| 'cancel_commands'
---| 'play_spine_animation'
---| 'copy_text'

---@alias RuntimeEventType
---| 'tap'
---| 'animation_done'
---| 'resize'
---| 'scroll'
---| 'network_http'
---| 'network_ws_open'
---| 'network_ws_message'
---| 'network_ws_error'
---| 'network_ws_close'

---@alias RuntimeScaleMode
---| 'fit'
---| 'fill'
---| 'stretch'
---| 'none'

---@alias RuntimeLayoutAlign
---| 'start'
---| 'center'
---| 'end'

---@alias RuntimeButtonVariant
---| 'primary'
---| 'secondary'
---| 'ghost'

---@class (exact) RuntimeNode
---@field id string
---@field type RuntimeNodeType
---@field parent? string
---@field asset? string Normal image/sprite/spine asset key. For button nodes this is the normal-state image.
---@field frame? string TexturePacker frame name within the asset atlas.
---@field pressedFrame? string Button pressed-state TexturePacker frame name.
---@field disabledFrame? string Button disabled-state TexturePacker frame name.
---@field sourceX? number Source atlas region x in image pixels.
---@field sourceY? number Source atlas region y in image pixels.
---@field sourceWidth? number Source atlas region width in image pixels.
---@field sourceHeight? number Source atlas region height in image pixels.
---@field sliceLeft? number Left nine-slice inset in source pixels.
---@field sliceTop? number Top nine-slice inset in source pixels.
---@field sliceRight? number Right nine-slice inset in source pixels.
---@field sliceBottom? number Bottom nine-slice inset in source pixels.
---@field pressedAsset? string Button pressed-state image asset key.
---@field disabledAsset? string Button disabled-state image asset key.
---@field animation? string
---@field skin? string
---@field loop? boolean
---@field text? string
---@field x? number
---@field y? number
---@field width? number
---@field height? number
---@field paddingLeft? number
---@field paddingTop? number
---@field paddingRight? number
---@field paddingBottom? number
---@field anchor? RuntimeAnchor
---@field layer? integer
---@field visible? boolean
---@field alpha? number
---@field scale? number
---@field rotation? number
---@field color? string
---@field fontSize? number
---@field textAlign? RuntimeTextAlign
---@field textShadowColor? string
---@field textShadowOffsetX? number
---@field textShadowOffsetY? number
---@field textShadowBlur? number
---@field radius? number
---@field strokeWidth? number
---@field value? number
---@field scrollX? number
---@field scrollY? number
---@field contentWidth? number
---@field contentHeight? number
---@field virtualized? boolean
---@field cacheExtent? number
---@field inertia? boolean
---@field scrollbarThumbColor? string
---@field scrollbarTrackColor? string
---@field scrollbarThickness? number
---@field scrollbarVisible? boolean
---@field interactive? boolean
---@field onTap? string
---@field onScroll? string
---@field preset? RuntimeParticlePreset
---@field count? integer
---@field duration? number
---@field speedMin? number
---@field speedMax? number
---@field gravityX? number
---@field gravityY? number
---@field spread? number
---@field colorTo? string
---@field radiusTo? number
---@field autoRemove? boolean
---@field fadeOut? boolean

---@class (exact) RuntimeNodeProps
---@field type? RuntimeNodeType
---@field parent? string
---@field asset? string Normal image/sprite/spine asset key. For button nodes this is the normal-state image.
---@field frame? string TexturePacker frame name within the asset atlas.
---@field pressedFrame? string Button pressed-state TexturePacker frame name.
---@field disabledFrame? string Button disabled-state TexturePacker frame name.
---@field sourceX? number Source atlas region x in image pixels.
---@field sourceY? number Source atlas region y in image pixels.
---@field sourceWidth? number Source atlas region width in image pixels.
---@field sourceHeight? number Source atlas region height in image pixels.
---@field sliceLeft? number Left nine-slice inset in source pixels.
---@field sliceTop? number Top nine-slice inset in source pixels.
---@field sliceRight? number Right nine-slice inset in source pixels.
---@field sliceBottom? number Bottom nine-slice inset in source pixels.
---@field pressedAsset? string Button pressed-state image asset key.
---@field disabledAsset? string Button disabled-state image asset key.
---@field animation? string
---@field skin? string
---@field loop? boolean
---@field text? string
---@field x? number
---@field y? number
---@field width? number
---@field height? number
---@field paddingLeft? number
---@field paddingTop? number
---@field paddingRight? number
---@field paddingBottom? number
---@field anchor? RuntimeAnchor
---@field layer? integer
---@field visible? boolean
---@field alpha? number
---@field scale? number
---@field rotation? number
---@field color? string
---@field fontSize? number
---@field textAlign? RuntimeTextAlign
---@field textShadowColor? string
---@field textShadowOffsetX? number
---@field textShadowOffsetY? number
---@field textShadowBlur? number
---@field radius? number
---@field strokeWidth? number
---@field value? number
---@field scrollX? number
---@field scrollY? number
---@field contentWidth? number
---@field contentHeight? number
---@field virtualized? boolean
---@field cacheExtent? number
---@field inertia? boolean
---@field scrollbarThumbColor? string
---@field scrollbarTrackColor? string
---@field scrollbarThickness? number
---@field scrollbarVisible? boolean
---@field interactive? boolean
---@field onTap? string
---@field onScroll? string
---@field preset? RuntimeParticlePreset
---@field count? integer
---@field duration? number
---@field speedMin? number
---@field speedMax? number
---@field gravityX? number
---@field gravityY? number
---@field spread? number
---@field colorTo? string
---@field radiusTo? number
---@field autoRemove? boolean
---@field fadeOut? boolean

---Helper-only fields accepted by runtime_ui/runtime_widgets. They are normalized
---before the node/update crosses the Dart Runtime protocol boundary.
---@class RuntimeNodeInit: RuntimeNodeProps
---@field w? number Alias for width.
---@field h? number Alias for height.
---@field size? number Alias for both width and height.
---@field handler? string Alias for onTap.
---@field onClick? string Alias for onTap.

---@class (exact) RuntimeNodeUpdate
---@field id string
---@field props RuntimeNodeProps

---@class (exact) RuntimeNodeRemove
---@field id string

---@class (exact) RuntimeDiffSection
---@field creates? RuntimeNode[]
---@field updates? RuntimeNodeUpdate[]
---@field removes? (string|RuntimeNodeRemove)[]

---@class (exact) RuntimeDiff
---@field render? RuntimeDiffSection
---@field ui? RuntimeDiffSection
---@field commands? RuntimeCommand[]

---@class (exact) RuntimeEvent
---@field type RuntimeEventType|string
---@field target? string
---@field handler? string
---@field x? number
---@field y? number
---@field data? table

---@class (exact) RuntimeCommand
---@field type RuntimeCommandType
---@field target? string
---@field scope? string
---@field id? string
---@field group? string
---@field commandGroup? string
---@field onComplete? string
---@field duration? number
---@field commands? RuntimeCommand[]
---@field path? RuntimePoint[]
---@field x? number
---@field y? number
---@field alpha? number
---@field scale? number
---@field angle? number
---@field text? string
---@field message? string
---@field asset? string
---@field name? string
---@field volume? number
---@field channel? string
---@field loop? boolean
---@field failOnError? boolean
---@field animation? string
---@field track? integer
---@field queue? boolean
---@field delay? number

---@class (exact) RuntimeCommandOpts
---@field id? string
---@field group? string
---@field commandGroup? string
---@field scope? string
---@field onComplete? string
---@field duration? number

---@class (exact) RuntimeAudioCommandOpts: RuntimeCommandOpts
---@field volume? number
---@field name? string

---@class (exact) RuntimeBgmCommandOpts: RuntimeAudioCommandOpts
---@field channel? string
---@field loop? boolean

---@class (exact) RuntimeSpineCommandOpts: RuntimeCommandOpts
---@field track? integer
---@field loop? boolean
---@field queue? boolean
---@field delay? number

---@class (exact) RuntimeResourceCommandOpts: RuntimeCommandOpts
---@field failOnError? boolean

---@class (exact) RuntimePoint
---@field x number
---@field y number

---@class (exact) RuntimeLocaleContext
---@field requested string
---@field resolved string
---@field default string
---@field supported string[]
---@field languageCode string
---@field scriptCode? string
---@field countryCode? string

---@class (exact) RuntimeScreenContext
---@field width number
---@field height number

---@class (exact) RuntimeDesignContext
---@field width number
---@field height number

---@class (exact) RuntimeViewportContext
---@field x number
---@field y number
---@field width number
---@field height number
---@field scaleX number
---@field scaleY number
---@field scaleMode RuntimeScaleMode|string

---@class (exact) RuntimeContext
---@field screen RuntimeScreenContext
---@field design RuntimeDesignContext
---@field viewport RuntimeViewportContext
---@field seed integer
---@field runtimeApiVersion integer
---@field gameId string
---@field gameVersion string
---@field locale? RuntimeLocaleContext

---@class RuntimeUi
---@field style fun(base?: RuntimeNodeProps, opts?: RuntimeNodeProps): RuntimeNodeProps
---@field with_parent fun(parent: string, opts?: RuntimeNodeProps): RuntimeNodeProps
---@field node fun(node_type: RuntimeNodeType, id: string, opts?: RuntimeNodeInit): RuntimeNode
---@field panel fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field rect fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field circle fun(id: string, x: number|RuntimeNodeInit, y?: number, size?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field line fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field progress fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, value?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field particle fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field text fun(id: string, text: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field button fun(id: string, text: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, handler?: string, opts?: RuntimeNodeInit): RuntimeNode
---@field list_view fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field image fun(id: string, asset: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field sprite fun(id: string, asset: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field spine fun(id: string, asset: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, animation?: string, opts?: RuntimeNodeInit): RuntimeNode
---@field update fun(id: string, props: RuntimeNodeInit): RuntimeNodeUpdate
---@field text_update fun(id: string, text: string): RuntimeNodeUpdate
---@field visible_update fun(id: string, visible: boolean): RuntimeNodeUpdate
---@field alpha_update fun(id: string, alpha: number): RuntimeNodeUpdate
---@field scale_update fun(id: string, scale: number): RuntimeNodeUpdate
---@field position_update fun(id: string, x: number, y: number): RuntimeNodeUpdate
---@field size_update fun(id: string, width: number, height: number): RuntimeNodeUpdate
---@field transform_update fun(id: string, x: number, y: number, scale: number, rotation: number): RuntimeNodeUpdate
---@field batch_update fun(ids: string[], props: RuntimeNodeInit): RuntimeNodeUpdate[]
---@field append fun(nodes: RuntimeNode[], node: RuntimeNode): RuntimeNode[]
---@field append_all fun(nodes: RuntimeNode[], extra_nodes: RuntimeNode[]): RuntimeNode[]

---@class (exact) RuntimeDialogButton
---@field id? string
---@field text string
---@field handler string
---@field color? string

---@class (exact) RuntimeDialogOpts
---@field screenWidth? number
---@field screenHeight? number
---@field overlay? boolean
---@field overlayColor? string
---@field blockInput? boolean
---@field layer? integer
---@field color? string
---@field radius? number
---@field panelStyle? RuntimeNodeProps
---@field titleColor? string
---@field titleSize? number
---@field titleStyle? RuntimeNodeProps
---@field messageColor? string
---@field messageSize? number
---@field messageStyle? RuntimeNodeProps
---@field buttons? RuntimeDialogButton[]
---@field buttonGap? number
---@field buttonStyle? RuntimeNodeProps

---@class RuntimeLabeledProgressOpts: RuntimeNodeInit
---@field labelHeight? number
---@field labelStyle? RuntimeNodeProps

---@class RuntimePillOpts: RuntimeNodeInit
---@field panelStyle? RuntimeNodeProps
---@field textStyle? RuntimeNodeProps

---@class RuntimeTextButtonOpts: RuntimeNodeInit
---@field variant? RuntimeButtonVariant

---@class RuntimeListItemOpts: RuntimeTextButtonOpts
---@field selected? boolean
---@field activeColor? string
---@field inactiveColor? string

---@class RuntimeTabItem
---@field id? string
---@field key? string
---@field text string
---@field handler? string
---@field selected? boolean

---@class RuntimeTabsOpts: RuntimeNodeInit
---@field tabs? RuntimeTabItem[]
---@field selected? string
---@field gap? number
---@field itemWidth? number
---@field itemHeight? number
---@field activeColor? string
---@field inactiveColor? string
---@field buttonStyle? RuntimeNodeProps

---@class RuntimeActionItem
---@field id? string
---@field text string
---@field handler? string
---@field visible? boolean
---@field color? string
---@field style? RuntimeNodeProps

---@class RuntimeActionRowOpts: RuntimeNodeInit
---@field actions? RuntimeActionItem[]
---@field gap? number
---@field itemWidth? number
---@field itemHeight? number
---@field buttonStyle? RuntimeNodeProps

---@class RuntimePanelHeaderOpts: RuntimeNodeInit
---@field eyebrow? string
---@field title string
---@field summary? string
---@field gap? number
---@field eyebrowId? string
---@field titleId? string
---@field summaryId? string
---@field eyebrowHeight? number
---@field titleHeight? number
---@field summaryHeight? number
---@field eyebrowStyle? RuntimeNodeProps
---@field titleStyle? RuntimeNodeProps
---@field summaryStyle? RuntimeNodeProps

---@class RuntimeWidgetTheme
---@field primary? string
---@field secondary? string
---@field success? string
---@field overlay? string
---@field surface? string
---@field surfaceAlt? string
---@field card? string
---@field text? string
---@field muted? string
---@field progress? string
---@field transparent? string

---@class RuntimeWidgets
---@field configure fun(tokens?: RuntimeWidgetTheme): RuntimeWidgets
---@field label fun(id: string, text: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field section_title fun(id: string, text: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field pill fun(id: string, text: string|RuntimePillOpts, x?: number, y?: number, width?: number, height?: number, opts?: RuntimePillOpts): RuntimeNode[]
---@field text_button fun(id: string, text: string|RuntimeTextButtonOpts, x?: number, y?: number, width?: number, height?: number, handler?: string, opts?: RuntimeTextButtonOpts): RuntimeNode
---@field list_item fun(id: string, text: string|RuntimeListItemOpts, x?: number, y?: number, width?: number, height?: number, handler?: string, opts?: RuntimeListItemOpts): RuntimeNode
---@field tabs fun(id: string, tabs: RuntimeTabItem[]|RuntimeTabsOpts, opts?: RuntimeTabsOpts): RuntimeNode[]
---@field action_row fun(id: string, actions: RuntimeActionItem[]|RuntimeActionRowOpts, opts?: RuntimeActionRowOpts): RuntimeNode[]
---@field panel_header fun(id: string, opts: RuntimePanelHeaderOpts): RuntimeNode[]
---@field overlay fun(id: string, width: number|RuntimeNodeInit, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field card fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field progress_bar fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, value?: number, opts?: RuntimeNodeInit): RuntimeNode
---@field labeled_progress fun(id: string, label: string, x: number, y: number, width: number, height: number, value: number, opts?: RuntimeLabeledProgressOpts): RuntimeNode[]
---@field button_row fun(parent: string, id: string, buttons: RuntimeDialogButton[], x: number, y: number, width: number, height: number, gap?: number, opts?: RuntimeNodeProps): RuntimeNode[]
---@field dialog fun(id: string, title: string, message: string, x: number, y: number, width: number, height: number, opts?: RuntimeDialogOpts): RuntimeNode[]

---@class (exact) RuntimeLayoutItem
---@field node RuntimeNode
---@field marginLeft? number
---@field marginRight? number
---@field marginTop? number
---@field marginBottom? number

---@class RuntimeLayoutItemOpts
---@field margin? number
---@field mx? number
---@field my? number
---@field ml? number
---@field mr? number
---@field mt? number
---@field mb? number
---@field marginLeft? number
---@field marginRight? number
---@field marginTop? number
---@field marginBottom? number

---@class RuntimeLinearLayoutOpts
---@field x? number
---@field y? number
---@field width? number
---@field height? number
---@field gap? number
---@field align? RuntimeLayoutAlign
---@field padding? number
---@field paddingX? number
---@field paddingY? number
---@field px? number
---@field py? number
---@field paddingLeft? number
---@field paddingTop? number

---@class RuntimeBoxLayoutOpts: RuntimeLinearLayoutOpts
---@field rows? integer
---@field columns? integer
---@field cols? integer
---@field cellWidth? number
---@field cellHeight? number
---@field cellW? number
---@field cellH? number
---@field gapX? number
---@field gapY? number
---@field valign? RuntimeLayoutAlign

---@class RuntimeLayout
---@field item fun(node: RuntimeNode, opts?: RuntimeLayoutItemOpts): RuntimeLayoutItem
---@field local_position fun(origin: RuntimePoint, position: RuntimePoint): RuntimePoint
---@field row fun(parent?: string, items: (RuntimeNode|RuntimeLayoutItem)[], opts?: RuntimeLinearLayoutOpts): RuntimeNode[]
---@field column fun(parent?: string, items: (RuntimeNode|RuntimeLayoutItem)[], opts?: RuntimeLinearLayoutOpts): RuntimeNode[]
---@field stack fun(parent?: string, items: (RuntimeNode|RuntimeLayoutItem)[], opts?: RuntimeLinearLayoutOpts): RuntimeNode[]
---@field box fun(parent?: string, items: (RuntimeNode|RuntimeLayoutItem)[], opts?: RuntimeBoxLayoutOpts): RuntimeNode[]

---@class RuntimeCommands
---@field toast fun(text: string, opts?: RuntimeCommandOpts): RuntimeCommand
---@field copy_text fun(text: string, opts?: RuntimeCommandOpts): RuntimeCommand
---@field delay fun(duration: number, opts?: RuntimeCommandOpts): RuntimeCommand
---@field sequence fun(items: RuntimeCommand[], opts?: RuntimeCommandOpts): RuntimeCommand
---@field parallel fun(items: RuntimeCommand[], opts?: RuntimeCommandOpts): RuntimeCommand
---@field move_path fun(target: string, path: RuntimePoint[], opts?: RuntimeCommandOpts): RuntimeCommand
---@field move_to fun(target: string, x: number, y: number, opts?: RuntimeCommandOpts): RuntimeCommand
---@field fade_to fun(target: string, alpha: number, opts?: RuntimeCommandOpts): RuntimeCommand
---@field scale_to fun(target: string, scale: number, opts?: RuntimeCommandOpts): RuntimeCommand
---@field rotate_to fun(target: string, angle: number, opts?: RuntimeCommandOpts): RuntimeCommand
---@field remove_node fun(target: string, opts?: RuntimeCommandOpts): RuntimeCommand
---@field play_spine_animation fun(target: string, animation: string, opts?: RuntimeSpineCommandOpts): RuntimeCommand
---@field play_sound fun(asset: string, opts?: RuntimeAudioCommandOpts): RuntimeCommand
---@field play_bgm fun(asset: string, opts?: RuntimeBgmCommandOpts): RuntimeCommand
---@field pause_bgm fun(channel?: string, opts?: RuntimeCommandOpts): RuntimeCommand
---@field resume_bgm fun(channel?: string, opts?: RuntimeCommandOpts): RuntimeCommand
---@field stop_bgm fun(channel?: string, opts?: RuntimeCommandOpts): RuntimeCommand
---@field preload_group fun(group: string, opts?: RuntimeResourceCommandOpts): RuntimeCommand
---@field evict_group fun(group: string, opts?: RuntimeCommandOpts): RuntimeCommand
---@field cancel_id fun(id: string): RuntimeCommand
---@field cancel_group fun(group: string): RuntimeCommand
---@field cancel_scope fun(scope: string): RuntimeCommand

---@class RuntimeHttpRequestOptions
---@field id? string
---@field method? string HTTP method. Defaults to GET.
---@field url string http/https URL.
---@field headers? table<string, string>
---@field body? string
---@field timeout? number Timeout in seconds. Defaults to 15.

---@class RuntimeWsConnectOptions
---@field id? string
---@field url string ws/wss URL.
---@field protocols? string[]

---@class RuntimeImportApi
---@field import fun(moduleName: string): table
---@field log fun(...: any)
---@field http_request fun(options: RuntimeHttpRequestOptions): string Starts an async HTTP request and returns request id. Result event type: network_http.
---@field ws_connect fun(options: RuntimeWsConnectOptions): string Opens a WebSocket and returns connection id. Event types: network_ws_open/network_ws_message/network_ws_error/network_ws_close.
---@field ws_send fun(id: string, message: string): boolean
---@field ws_close fun(id: string): boolean

---@type RuntimeImportApi
runtime = runtime

---@alias PlayerColor 'red'|'yellow'|'blue'|'green'
---@alias GamePhase 'waiting_roll'|'waiting_piece'|'animating'|'game_over'
---@alias PieceStatus 'home'|'route'|'finished'

---@class (exact) PieceState
---@field id string
---@field owner PlayerColor
---@field progress integer
---@field status PieceStatus

---@class (exact) LudoState
---@field current_player PlayerColor
---@field phase GamePhase
---@field dice_index integer
---@field dice_values integer[]
---@field dice? integer
---@field selected_piece? string
---@field pending_move? table
---@field winner? PlayerColor
---@field players PlayerColor[]
---@field pieces table<string, PieceState>

---@class (exact) BoardPoint
---@field x number
---@field y number

---@class (exact) BoardData
---@field red_home BoardPoint[]
---@field blue_home BoardPoint[]
---@field path BoardPoint[]
---@field start table<PlayerColor, integer>