// Picotron v0.2.1e Global API Type Definitions

// =====================
// Userdata
// =====================
type UserdataType = 'u8' | 'i16' | 'i32' | 'i64' | 'f64'
type UserdataDim = '1d' | '2d'

// Userdata interface
interface Userdata<T = UserdataType, D = UserdataDim> {
  // Dimension methods
  width(): number
  height(): number | null
  /**
   * Returns width, height, type, dimensionality
   */
  attribs(): LuaMultiReturn<[number, number, T, number]>

  // Element access — 1D
  get(x: number): D extends '1d' ? number : LuaMultiReturn<number[]>
  get(x: number, n: number): D extends '1d' ? LuaMultiReturn<number[]> : number

  // Element access — 2D
  // No n specified (defaults to 1, returns single number)
  get(x: number, y: number): D extends '2d' ? number : LuaMultiReturn<number[]>
  // n = 0 (fast path, returns single number)
  get(x: number, y: number, n: 0): D extends '2d' ? number : LuaMultiReturn<number[]>
  // n specified (returns multiple values)
  get(x: number, y: number, n: number): D extends '2d' ? LuaMultiReturn<number[]> : number

  set(x: number, ...values: number[]): void
  set(x: number, y: number, ...values: number[]): void

  // Row/Column access (2d only)
  row(i: number): Userdata<T> | null
  column(i: number): Userdata<T> | null

  // Binary operations
  add(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  sub(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  mul(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  div(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  mod(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  pow(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>

  // Bitwise operations
  band(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  bor(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  bxor(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>

  // Min/Max operations
  max(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  min(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>

  // Unary operations
  copy(
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  abs(
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  sgn(
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>
  sgn0(
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>

  // Lookup table copy
  take(
    idx: Userdata<'i32'>,
    dest?: Userdata<T>,
    idx_offset?: number,
    dest_offset?: number,
    span_len?: number,
    idx_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>

  // Blit operation
  blit(
    dest?: Userdata<T>,
    src_x?: number,
    src_y?: number,
    dest_x?: number,
    dest_y?: number,
    width?: number,
    height?: number
  ): void

  // Mutation and conversion
  mutate(data_type: UserdataType, width?: number, height?: number): void
  convert(data_type: UserdataType, dest?: Userdata): Userdata

  // Interpolation
  lerp(
    offset?: number,
    len?: number,
    el_stride?: number,
    num_lerps?: number,
    lerp_stride?: number
  ): Userdata<T>

  // Sorting (2d only)
  sort(index?: number, descending?: boolean): void

  // Memory operations
  peek(addr: number, offset?: number, elements?: number): void
  poke(addr: number, offset?: number, elements?: number): void

  // Matrix/Vector operations (f64 only)
  matmul(m: Userdata<'f64'>, m_out?: Userdata<'f64'>, batch_height?: number): Userdata<'f64'>
  matmul3d(m: Userdata<'f64'>, m_out?: Userdata<'f64'>, batch_height?: number): Userdata<'f64'>
  transpose(m_out?: Userdata<T> | true): Userdata<T>

  // Vector operations (f64 only)
  magnitude(): number
  distance(v: Userdata<'f64'>): number
  dot(v: Userdata<'f64'>): number
  cross(v: Userdata<'f64'>, v_out?: Userdata<'f64'> | true): Userdata<'f64'>
}

// =====================
// Math Functions
// =====================
declare function abs(x: number): number
declare function atan2(dx: number, dy: number): number
declare function cos(x: number): number
declare function flr(x: number): number
declare function max(x: number, ...args: number[]): number
declare function mid(x: number, y: number, z: number): number
declare function min(x: number, ...args: number[]): number
declare function rnd(x?: number): number
declare function sgn(x: number): number
declare function sin(x: number): number
declare function sqrt(x: number): number
declare function srand(seed: number): void

// =====================
// Bitwise operations
// =====================
declare function band(x: number, ...args: number[]): number
declare function bnot(x: number): number
declare function bor(x: number, ...args: number[]): number
declare function bxor(x: number, ...args: number[]): number
declare function rotl(x: number, n: number): number
declare function rotr(x: number, n: number): number
declare function shl(x: number, n: number): number
declare function shr(x: number, n: number): number

// =====================
// Graphics API
// =====================
declare function cls(color?: number): void
declare function camera(x?: number, y?: number): void
declare function clip(x?: number, y?: number, w?: number, h?: number): void
declare function color(c: number): void
declare function pal(c0?: number, c1?: number, p?: number): void
declare function palt(c?: number, t?: boolean): void
declare function fillp(pattern?: number): void
declare function pget(x: number, y: number): number
declare function pset(x: number, y: number, c?: number): void
declare function cursor(x?: number, y?: number, c?: number): void
declare function print(text?: any, x?: number, y?: number, color?: number): number
declare function line(x1: number, y1: number, x2?: number, y2?: number, color?: number): void
declare function line(userdata: Userdata): void
declare function rect(x0: number, y0: number, x1: number, y1: number, c?: number): void
declare function rect(userdata: Userdata): void
declare function rectfill(x0: number, y0: number, x1: number, y1: number, c?: number): void
declare function rectfill(userdata: Userdata): void
declare function circ(x: number, y: number, r: number, c?: number): void
declare function circfill(x: number, y: number, r: number, c?: number): void
declare function circfill(userdata: Userdata): void
declare function oval(x: number, y: number, rx: number, ry: number, c?: number): void
declare function ovalfill(x: number, y: number, rx: number, ry: number, c?: number): void
declare function rrect(
  x: number,
  y: number,
  width: number,
  height: number,
  radius?: number,
  c?: number
): void
declare function rrectfill(
  x: number,
  y: number,
  width: number,
  height: number,
  radius?: number,
  c?: number
): void
declare function fget(n: number): number
declare function fget(n: number, f: number): boolean
declare function fset(n: number, f?: number, val?: boolean): void
declare function get_spr(index: number): Userdata<'u8'>
declare function set_spr(index: number, ud: Userdata<'u8'>): void
declare function spr(
  sprite: number | Userdata,
  x: number,
  y: number,
  flip_x?: boolean,
  flip_y?: boolean
): void
declare function sspr(
  sx: number,
  sy: number,
  sw: number,
  sh: number,
  dx: number,
  dy: number,
  dw?: number,
  dh?: number,
  flip_x?: boolean,
  flip_y?: boolean
): void

// =====================
// Map API
// =====================
declare function map(
  cel_x?: number,
  cel_y?: number,
  sx?: number,
  sy?: number,
  cel_w?: number,
  cel_h?: number,
  layer?: number
): void
declare function map(
  src: Userdata<'i16'>,
  cel_x?: number,
  cel_y?: number,
  sx?: number,
  sy?: number,
  cel_w?: number,
  cel_h?: number,
  layer?: number,
  tile_w?: number,
  tile_h?: number
): void
declare function mget(cel_x: number, cel_y: number): number
declare function mset(cel_x: number, cel_y: number, sprite_number: number): void
declare function tline3d(
  src: number | Userdata<'u8'> | Userdata<'i16'>,
  x0: number,
  y0: number,
  x1: number,
  y1: number,
  u0: number,
  v0: number,
  u1: number,
  v1: number,
  w0?: number,
  w1?: number,
  flags?: number
): void
declare function tline3d(
  x0: number,
  y0: number,
  x1: number,
  y1: number,
  u0: number,
  v0: number,
  u1: number,
  v1: number,
  w0?: number,
  w1?: number,
  flags?: number
): void

// =====================
// Audio API
// =====================
declare function sfx(
  id: number,
  channel?: number,
  offset?: number,
  length?: number,
  mix_volume?: number
): void
declare function music(
  id?: number,
  fade_len?: number,
  channel_mask?: number,
  base_addr?: number,
  tick_offset?: number
): void
declare function note(
  pitch?: number,
  inst?: number,
  vol?: number,
  effect?: number,
  effect_p?: number,
  channel?: number,
  retrig?: boolean,
  panning?: number
): void

// =====================
// Input API
// =====================
declare function btn(i?: number, player?: number): number | boolean
declare function btnp(i?: number, player?: number): number | boolean
declare function key(k?: string, raw?: boolean): boolean
declare function keyp(k?: string, raw?: boolean): boolean
declare function peektext(): boolean
declare function readtext(clear?: boolean): string
declare function mouse(): LuaMultiReturn<[number, number, number, number, number]>
declare function mouselock(
  lock: boolean,
  event_sensitivity?: number,
  move_sensitivity?: number
): LuaMultiReturn<[number, number]>
declare function input(prompt?: string, flags?: number): string | null

// =====================
// String API
// =====================
declare function chr(...values: number[]): string
declare function ord(
  str: string,
  index?: number,
  num_results?: number
): number | LuaMultiReturn<number[]>
declare function sub(str: string, pos0: number, pos1?: number | boolean): string
declare function split(
  str: string,
  delimiter?: string | number,
  convert_numbers?: boolean
): string[]
declare function type(val: any): string
declare function tostr(val: any, format?: string): string
declare function tonum(str: string): number | null
declare function create_delta(str0: string, str1: string): string
declare function apply_delta(str0: string, delta: string): string | null

// =====================
// Tables API
// =====================
declare function add(t: any[], item: any, index?: number): void
declare function del(t: any[], item: any): void
declare function deli(t: any[], index: number): any
declare function count(t: any[]): number
declare function all(t: any[]): () => any | undefined
declare function foreach(t: any[], fn: (item: any) => void): void
declare function pairs(
  t: any
): LuaMultiReturn<[(t: any, k?: any) => LuaMultiReturn<[any, any]>, any, any]>
declare function next(t: any, k?: any): LuaMultiReturn<[any, any]>

// =====================
// PODs API
// =====================
declare function pod(val: any, flags?: number, metadata?: any): string
declare function unpod(str: string): LuaMultiReturn<[any, any]>
declare function store(path: string, val: any): void
declare function fetch(path: string): any

// =====================
// Files API
// =====================
declare function store(filename: string, obj: any, metadata?: any): void
declare function fetch(filename: string, options?: any): LuaMultiReturn<[any, any]>
declare function store_metadata(filename: string, metadata: any): void
declare function fetch_metadata(filename: string): any
declare function include(path: string): void
declare function cd(path: string): void
declare function ls(path?: string): string[]
declare function mkdir(path: string): void
declare function rm(path: string): void
declare function mv(src: string, dest: string): void
declare function cp(src: string, dest: string): void
declare function pwd(): string
declare function fullpath(filename: string): string
declare function fstat(path: string): LuaMultiReturn<[string, number, string]>

// =====================
// System API
// =====================
declare function load(path: string): void
declare function save(path: string): void
declare function run(): void
declare function stop(message?: string): void
declare function resume(): void
declare function reset(cart?: string): void
declare function stat(v: number, ...args: any[]): any
declare function env(): any
declare function time(): number
declare function t(): number
declare function date(format?: string, t?: string | number, delta?: number): string
declare function exit(): void
declare function printh(
  text: any,
  file_path?: string,
  overwrite?: boolean,
  terminal?: boolean
): void
declare function error(description?: string): void
declare function assert(condition: any, message?: string): void
declare function get_clipboard(): string
declare function set_clipboard(text: string): void
declare function create_process(filename: string, ...args: any[]): number
declare function pid(): number
declare function signal(proc_id: number, signal: string): void
declare function send_message(
  proc_id: number,
  msg: any,
  reply?: boolean | ((msg: any) => void)
): any
declare function on_event(event: string, func: (msg: any) => boolean | void): void

// =====================
// Memory API
// =====================
declare function peek(addr: number, count?: number): number | LuaMultiReturn<number[]>
declare function poke(addr: number, ...values: number[]): void
declare function peek2(addr: number): number
declare function poke2(addr: number, val: number): void
declare function peek4(addr: number): number
declare function poke4(addr: number, val: number): void
declare function peek8(addr: number): number
declare function poke8(addr: number, val: number): void
declare function memcpy(dest_addr: number, src_addr: number, count: number): void
declare function memset(addr: number, value: number, count: number): void
declare function reload(dest_addr: number, src_addr: number, count: number, filename?: string): void
declare function memmap(ud: Userdata, addr: number): void

// =====================
// Userdata API
// =====================
// 1D creation (width only) — allow specifying only D; T is inferred from first argument
declare function userdata<D extends '1d' = '1d', T extends UserdataType = UserdataType>(
  data_type: T,
  width: number,
  ...data: number[]
): Userdata<T, D>
// 2D creation (width + height) — allow specifying only D; T is inferred from first argument
declare function userdata<D extends '2d' = '2d', T extends UserdataType = UserdataType>(
  data_type: T,
  width: number,
  height: number,
  ...data: number[]
): Userdata<T, D>
// GFX string always yields 2D u8
declare function userdata(gfx_string: string): Userdata<'u8', '2d'>
// Vector helper produces 1D f64
declare function vec(...values: number[]): Userdata<'f64', '1d'>
declare function get(
  u: Userdata | null | undefined,
  x: number,
  n?: number
): LuaMultiReturn<number[]>
declare function get(
  u: Userdata | null | undefined,
  x: number,
  y: number,
  n?: number
): LuaMultiReturn<number[]>
declare function set(u: Userdata | null | undefined, x: number, ...values: number[]): void
declare function set(
  u: Userdata | null | undefined,
  x: number,
  y: number,
  ...values: number[]
): void
declare function blit(
  src?: Userdata,
  dest?: Userdata,
  src_x?: number,
  src_y?: number,
  dest_x?: number,
  dest_y?: number,
  width?: number,
  height?: number
): void
declare function matmul(
  m0: Userdata<'f64'>,
  m1: Userdata<'f64'>,
  m_out?: Userdata<'f64'>,
  batch_height?: number
): Userdata<'f64'>
declare function matmul3d(
  m0: Userdata<'f64'>,
  m1: Userdata<'f64'>,
  m_out?: Userdata<'f64'>,
  batch_height?: number
): Userdata<'f64'>

// =====================
// Window API
// =====================
declare function window(
  attributes?: Partial<{
    width: number
    height: number
    title: string
    pauseable: boolean
    tabbled: boolean
    has_frame: boolean
    resizeable: boolean
    wallpapier: boolean
    autoclose: boolean
    z: number
    cursor: 0 | 1 | Userdata
    squashable: boolean
    background_updates: boolean
    background_draws: boolean
  }>
): any
declare function window(width: number, height: number): any
declare function get_display(): Userdata<'u8'>
declare function set_draw_target(ud?: Userdata<'u8'>): void
declare function get_draw_target(): Userdata<'u8'>
declare function vid(mode: number): void

// =====================
// Undo Stacks
// =====================
interface UndoStack {
  checkpoint(extra?: any): void
  undo(peek?: boolean): any
  redo(peek?: boolean): any
}
declare function create_undo_stack(
  save: (item?: any) => any,
  load: (dat: any, item?: any) => void,
  pod_flags?: number,
  item?: any
): UndoStack

// =====================
// Sockets
// =====================
interface Socket {
  read(): string | LuaMultiReturn<[null, string]>
  write(str: string): number | LuaMultiReturn<[null, string]>
  close(): void
  status(): 'ready' | 'listening' | 'closed' | 'closed by peer' | 'disconnected'
  accept(): Socket | null
}
declare function socket(addr: string): Socket | null

// =====================
// Userdata Memory
// =====================
declare function unmap(ud: Userdata, addr?: number): void

// =====================
// Graphical User Interface
// =====================
interface GuiMsg {
  event: string
  mx: number
  my: number
  mb: number
  dx: number
  dy: number
  mx0?: number // drag start position
  my0?: number
  wheel_x: number
  wheel_y: number
  has_pointer: boolean
  last_mb?: number
  propagate_to_children?: boolean
}

// Properties that can be passed when creating/attaching elements
interface GuiElementAttribs {
  x?: number
  y?: number
  z?: number
  width?: number
  height?: number
  width0?: number
  height0?: number
  
  // Relative sizing
  width_rel?: number
  height_rel?: number
  width_add?: number
  height_add?: number
  
  // Layout
  justify?: 'left' | 'center' | 'right'
  vjustify?: 'top' | 'center' | 'bottom'
  clip_to_parent?: boolean
  confine_to_clip?: boolean
  squash_to_clip?: boolean
  confine_to_parent?: boolean
  squash_to_parent?: boolean
  min_width?: number
  min_height?: number
  
  // Appearance
  label?: string
  cursor?: string | number
  bgcol?: number
  fgcol?: number
  border?: number
  highlight?: boolean
  hidden?: boolean
  ghost?: boolean
  
  // Custom properties
  action?: (this: GuiElement) => void
  divider?: boolean
  icon?: number | Userdata
  shortcut?: string
  stay_open?: boolean
  autohide?: boolean
  
  // For fields
  get?: (this: GuiElement) => string
  set?: (this: GuiElement, val: string) => void
  print_prefix?: string
  str?: string
  
  // Event handlers
  click?: (this: GuiElement, msg: GuiMsg) => boolean | void
  doubleclick?: (this: GuiElement, msg: GuiMsg) => boolean | void
  doubletap?: (this: GuiElement, msg: GuiMsg) => boolean | void
  drag?: (this: GuiElement, msg: GuiMsg) => boolean | void
  release?: (this: GuiElement, msg: GuiMsg) => boolean | void
  tap?: (this: GuiElement, msg: GuiMsg) => boolean | void
  mousewheel?: (this: GuiElement, msg: GuiMsg) => boolean | void
  hover?: (this: GuiElement, msg: GuiMsg) => boolean | void
  update?: (this: GuiElement, msg: GuiMsg) => boolean | void
  draw?: (this: GuiElement, msg: GuiMsg) => void
  test_point?: (this: GuiElement, x: number, y: number) => boolean
}

interface GuiElement extends GuiElementAttribs {
  // Always exist after creation (set by GuiElement:new)
  z: number
  sx: number
  sy: number
  clip_to_parent: boolean
  child: GuiElement[]
  t0: number
  
  // Set during attach
  parent?: GuiElement
  head: Gui
  
  // Click tracking (set by gui internally)
  last_click_t?: number
  last_click_mb?: number
  last_tap_t?: number
  last_tap_mb?: number
  
  // Methods
  attach<T extends GuiElementAttribs & Record<string, unknown>>(
    child?: T
  ): GuiElement & T
  attach_button<T extends GuiElementAttribs & Record<string, unknown>>(
    el: T
  ): GuiElement & T & { label: string; width: number; height: number; cursor: string; bgcol: number; fgcol: number; border: number }
  attach_pulldown<T extends GuiElementAttribs & Record<string, unknown>>(
    el: T
  ): GuiElement & T & { item_y: number; item_h: number }
  attach_pulldown_item<T extends GuiElementAttribs & Record<string, unknown>>(
    el: T
  ): GuiElement & T & { label: string; x: number; y: number; width: number; height: number }
  attach_field<T extends GuiElementAttribs & Record<string, unknown>>(
    el: T
  ): GuiElement & T
  attach_scrollbars(attribs?: { autohide?: boolean }): GuiElement
  attach_text_editor(...args: any[]): GuiElement
  detach(el?: GuiElement): GuiElement | void
  bring_to_front(): void
  push_to_back(): void
  has_keyboard_focus(): boolean
  set_keyboard_focus(val: boolean): void
  event(msg: GuiMsg): void
}

interface Gui extends GuiElement {
  // Always set for root gui
  x: number
  y: number
  width: number
  height: number
  
  pointer_element?: GuiElement
  keyboard_focus_el?: GuiElement
  mouse_cursor_gfx?: string | number | false
  
  update_all(): void
  draw_all(): void
  get_pointer_element(): GuiElement | undefined
  get_keyboard_focus_element(): GuiElement | undefined
  el_at_xy(x: number, y: number): GuiElement | undefined
  el_at_pointer(x: number, y: number): GuiElement | undefined
  new<T extends GuiElementAttribs & Record<string, unknown>>(el: T): GuiElement & T
}

declare function create_gui(head_el?: GuiElementAttribs): Gui

// =====================
// Main Loop Callbacks
// =====================
declare var _init: () => void
declare var _draw: () => void
declare var _update: () => void
declare var _update60: () => void