initial commit

lua/api/core/ble.lua

@@ -0,0 +1,63 @@
+---@meta
+
+-- Generated from native/src/bindings/core/ble.cpp. Do not edit.
+
+---@class BleDevice
+---@field name string
+---@field address string
+---@field rssi integer
+
+---@class BleLib
+ble = {}
+
+---Starts the BLE stack.
+---@param name? string Local device name.
+---@return true? ok
+---@return string? error
+function ble.init(name) end
+
+---Stops the BLE stack and releases its memory.
+function ble.deinit() end
+
+---Scans for advertising devices.
+---@param durationMs? integer Defaults to 3000.
+---@return BleDevice[]? devices
+---@return string? error
+function ble.scan(durationMs) end
+
+---Connects to a peripheral.
+---@param address string
+---@return true? ok
+---@return string? error
+function ble.connect(address) end
+
+---Disconnects from the connected peripheral.
+function ble.disconnect() end
+
+---Whether a peripheral is connected.
+---@return boolean
+function ble.isConnected() end
+
+---Reads a characteristic value.
+---@param serviceUuid string
+---@param characteristicUuid string
+---@return string? value
+---@return string? error
+function ble.read(serviceUuid, characteristicUuid) end
+
+---Writes a characteristic value.
+---@param serviceUuid string
+---@param characteristicUuid string
+---@param value string
+---@return true? ok
+---@return string? error
+function ble.write(serviceUuid, characteristicUuid, value) end
+
+---Starts advertising.
+---@param name? string Advertised device name.
+---@return true? ok
+---@return string? error
+function ble.startAdvertising(name) end
+
+---Stops advertising.
+function ble.stopAdvertising() end

lua/api/core/fs.lua

@@ -0,0 +1,79 @@
+---@meta
+
+-- Generated from native/src/bindings/core/fs.cpp. Do not edit.
+
+---@class FsLib
+---@field MAX_READ_BYTES integer Largest portable whole-file or line read.
+fs = {}
+fs.MAX_READ_BYTES = 65536
+
+---Whether a path exists.
+---@param path string Absolute SD-card path; traversal components are rejected.
+---@return boolean
+function fs.exists(path) end
+
+---Returns the size of a file in bytes.
+---@param path string Absolute SD-card path.
+---@return integer? size
+---@return string? error Present when the path is missing or not a file.
+function fs.fileSize(path) end
+
+---Lists the directories in a directory.
+---@param path string Absolute directory path.
+---@return string[]? names Sorted names, excluding hidden entries.
+---@return string? error
+function fs.listDirs(path) end
+
+---Lists the files in a directory.
+---@param path string Absolute directory path.
+---@return string[]? names Sorted names, excluding hidden entries.
+---@return string? error
+function fs.listFiles(path) end
+
+---Creates a directory.
+---@param path string Absolute directory path.
+---@return true? ok
+---@return string? error
+function fs.mkdir(path) end
+
+---Reads a whole file.
+---@param path string Absolute file path.
+---@param maxBytes integer Maximum bytes to allocate, up to fs.MAX_READ_BYTES; oversized files fail rather than truncate.
+---@return string? content
+---@return string? error
+function fs.readFile(path, maxBytes) end
+
+---Reads one line starting at a byte offset.
+---@param path string Absolute file path.
+---@param offset integer Zero-based byte offset; a mid-line offset advances to the next line.
+---@param maxBytes integer Maximum line bytes to allocate, up to fs.MAX_READ_BYTES.
+---@return string? line Nil at end of file or on failure.
+---@return integer? nextOffset Byte offset of the following line.
+---@return string? error Present when the file cannot be read or the line exceeds maxBytes.
+function fs.readLineAt(path, offset, maxBytes) end
+
+---Removes a file.
+---@param path string Absolute file path. Firmware-protected roots cannot be removed.
+---@return true? ok
+---@return string? error
+function fs.remove(path) end
+
+---Removes a directory and everything below it.
+---@param path string Absolute directory path. Firmware-protected roots cannot be removed.
+---@return true? ok
+---@return string? error
+function fs.removeTree(path) end
+
+---Renames a file or directory.
+---@param source string Absolute source path.
+---@param destination string Absolute destination path, which must not exist.
+---@return true? ok
+---@return string? error
+function fs.rename(source, destination) end
+
+---Atomically replaces the destination or leaves its previous contents intact.
+---@param path string Absolute file path.
+---@param content string
+---@return true? ok
+---@return string? error
+function fs.writeFile(path, content) end

lua/api/core/gui.lua

@@ -0,0 +1,151 @@
+---@meta
+
+-- Generated from native/src/bindings/core/gui.cpp. Do not edit.
+
+---@alias GuiColor integer
+---@alias GuiFont integer
+---@alias GuiTextStyle integer
+
+---@class GuiLib
+---@field FONT_SMALL GuiFont Small auxiliary text.
+---@field FONT_UI GuiFont Normal controls and labels.
+---@field FONT_BODY GuiFont Normal reading text.
+---@field FONT_LARGE GuiFont Headings and prominent values.
+---@field STYLE_NORMAL GuiTextStyle
+---@field STYLE_BOLD GuiTextStyle
+gui = {}
+gui.FONT_SMALL = 0
+gui.FONT_UI = 0
+gui.FONT_BODY = 0
+gui.FONT_LARGE = 0
+gui.STYLE_NORMAL = 0
+gui.STYLE_BOLD = 0
+
+---Returns the live frame width.
+---@return integer
+function gui.getWidth() end
+
+---Returns the live frame height.
+---@return integer
+function gui.getHeight() end
+
+---Rotates the live frame without changing the saved preference.
+---@param degrees integer 0, 90, 180, or 270 clockwise.
+function gui.setRotation(degrees) end
+
+---Returns the rotation of the live frame.
+---@return integer Degrees clockwise for the live frame.
+function gui.getRotation() end
+
+---Returns an opaque native color. E-ink implementations quantize RGB to available grayscale.
+---@param r integer 0 through 255.
+---@param g integer 0 through 255.
+---@param b integer 0 through 255.
+---@return GuiColor
+function gui.color(r, g, b) end
+
+---Clears the frame.
+---@param color? GuiColor Defaults to white.
+function gui.clear(color) end
+
+---Fills a rectangle.
+---@param x integer
+---@param y integer
+---@param w integer
+---@param h integer
+---@param color GuiColor
+function gui.fillRect(x, y, w, h, color) end
+
+---Outlines a rectangle.
+---@param x integer
+---@param y integer
+---@param w integer
+---@param h integer
+---@param color GuiColor
+function gui.drawRect(x, y, w, h, color) end
+
+---Draws a line.
+---@param x1 integer
+---@param y1 integer
+---@param x2 integer
+---@param y2 integer
+---@param color GuiColor
+---@param width? integer Defaults to one pixel.
+function gui.drawLine(x1, y1, x2, y2, color, width) end
+
+---Draws a single pixel.
+---@param x integer
+---@param y integer
+---@param color GuiColor
+function gui.drawPixel(x, y, color) end
+
+---Outlines a circle.
+---@param x integer Center.
+---@param y integer Center.
+---@param radius integer
+---@param color GuiColor
+---@param width? integer Defaults to one pixel.
+function gui.drawCircle(x, y, radius, color, width) end
+
+---Fills a circle.
+---@param x integer Center.
+---@param y integer Center.
+---@param radius integer
+---@param color GuiColor
+---@param background? GuiColor Surface behind an anti-aliased edge.
+function gui.fillCircle(x, y, radius, color, background) end
+
+---Draws an anti-aliased rounded fill, optional gradient, and optional border in one pass.
+---@param x integer
+---@param y integer
+---@param w integer
+---@param h integer
+---@param radius integer
+---@param background GuiColor Surface behind the anti-aliased edge.
+---@param top? GuiColor Fill, or gradient top; omitted for no fill.
+---@param bottom? GuiColor Gradient bottom; defaults to top. Panels without a gradient use top.
+---@param border? GuiColor Omitted for no border.
+function gui.roundRect(x, y, w, h, radius, background, top, bottom, border) end
+
+---Temporarily gives the app the full panel, including firmware chrome.
+---@param on boolean
+function gui.setFullscreen(on) end
+
+---Fills a polygon.
+---@param xs integer[]
+---@param ys integer[]
+---@param color GuiColor
+function gui.fillPolygon(xs, ys, color) end
+
+---Draws a bitmap.
+---@param path string Absolute BMP path.
+---@param x? integer Left edge; defaults to centered.
+---@param y? integer Top edge; defaults to centered.
+---@param maxWidth? integer Defaults to panel width.
+---@param maxHeight? integer Defaults to panel height.
+---@return true? ok
+---@return string? error
+function gui.drawBmp(path, x, y, maxWidth, maxHeight) end
+
+---Measures a text run.
+---@param font GuiFont Use a named gui.FONT_* role.
+---@param text string
+---@param style? GuiTextStyle Defaults to gui.STYLE_NORMAL.
+---@return integer
+function gui.getTextWidth(font, text, style) end
+
+---Returns the line height of a font role.
+---@param font GuiFont Use a named gui.FONT_* role.
+---@param style? GuiTextStyle Defaults to gui.STYLE_NORMAL.
+---@return integer
+function gui.getFontHeight(font, style) end
+
+---Draws a text run with its top-left corner at x, y.
+---@param font GuiFont Use a named gui.FONT_* role.
+---@param x integer Left edge.
+---@param y integer Top edge.
+---@param text string
+---@param color? GuiColor Defaults to black.
+---@param style? GuiTextStyle Defaults to gui.STYLE_NORMAL.
+---@param background? GuiColor Omitted for transparent text.
+function gui.drawText(font, x, y, text, color, style, background) end

lua/api/core/http.lua

@@ -0,0 +1,71 @@
+---@meta
+
+-- Generated from native/src/bindings/core/http.cpp. Do not edit.
+
+---@class HttpRequestOptions
+---@field maxBytes integer Maximum response-body bytes to allocate, up to http.MAX_RESPONSE_BYTES; zero is valid for HEAD.
+---@field headers? table<string, string>
+
+---@class HttpResponse
+---@field status integer HTTP status code.
+---@field body string Response body, including for non-2xx responses.
+
+---@class HttpDownloadOptions
+---@field maxBytes integer Required maximum, from 1 through 16777216.
+---@field expectedSize? integer Exact expected byte count.
+---@field sha256? string Exact expected SHA-256 as 64 hexadecimal characters.
+
+---@class HttpLib
+---@field MAX_RESPONSE_BYTES integer Largest portable in-memory response body.
+http = {}
+http.MAX_RESPONSE_BYTES = 65536
+
+---Performs a GET request.
+---@param url string
+---@param options HttpRequestOptions
+---@return HttpResponse? response
+---@return string? error Transport failure or response body exceeding maxBytes.
+function http.get(url, options) end
+
+---Performs a HEAD request.
+---@param url string
+---@param options HttpRequestOptions
+---@return HttpResponse? response Body is empty.
+---@return string? error
+function http.head(url, options) end
+
+---Performs a DELETE request.
+---@param url string
+---@param options HttpRequestOptions
+---@return HttpResponse? response
+---@return string? error
+function http.delete(url, options) end
+
+---Performs a POST request.
+---@param url string
+---@param body string
+---@param options HttpRequestOptions
+---@return HttpResponse? response
+---@return string? error
+function http.post(url, body, options) end
+
+---Performs a PATCH request.
+---@param url string
+---@param body string
+---@param options HttpRequestOptions
+---@return HttpResponse? response
+---@return string? error
+function http.patch(url, body, options) end
+
+---Streams authenticated HTTPS to a new file and removes partial or unverified output.
+---@param url string HTTPS URL.
+---@param destination string Absolute path which must not exist.
+---@param options HttpDownloadOptions
+---@return integer? bytesWritten
+---@return string? error
+function http.download(url, destination, options) end
+
+---Percent-encodes a string for use in a URL.
+---@param input string
+---@return string
+function http.urlencode(input) end

lua/api/core/log.lua

@@ -0,0 +1,18 @@
+---@meta
+
+-- Generated from native/src/bindings/core/log.cpp. Do not edit.
+
+---@class LogLib
+log = {}
+
+---Writes a debug message to the firmware log.
+---@param message string
+function log.debug(message) end
+
+---Writes an informational message to the firmware log.
+---@param message string
+function log.info(message) end
+
+---Writes an error message to the firmware log.
+---@param message string
+function log.error(message) end

lua/api/core/node.lua

@@ -0,0 +1,155 @@
+---@meta
+
+-- Generated from native/src/bindings/core/node.cpp. Do not edit.
+
+---@alias NodeId integer
+---@alias NodeType "box"|"text"|"button"|"custom"
+---@alias NodeDirection "up"|"down"|"left"|"right"
+
+---@class NodeSpec
+---@field type NodeType
+---@field w? number|"fill"|"auto"
+---@field h? number|"fill"|"auto"
+---@field pad? number
+---@field gap? number
+---@field align? "start"|"center"|"end"|"stretch"
+---@field justify? "start"|"center"|"end"|"between"
+---@field row? boolean
+---@field at? table Absolute-position fields.
+---@field capture? boolean
+---@field interactive? boolean
+---@field label? string
+---@field font? GuiFont
+
+---@class NodeStyle
+---@field color? GuiColor
+---@field background? GuiColor Background offered to descendants.
+---@field fill? GuiColor Surface painted by a box.
+---@field border? GuiColor
+---@field face? GuiColor Default button surface.
+---@field pressedFace? GuiColor Pressed button surface.
+---@field pressedColor? GuiColor Pressed button text.
+---@field focusColor? GuiColor Distinct outline for directional focus.
+---@field radius? integer
+---@field font? GuiFont
+---@field textStyle? GuiTextStyle
+
+---@class NodeLib
+node = {}
+
+---Drops the current tree; all existing IDs become invalid.
+function node.reset() end
+
+---Creates a node, optionally as a child of an existing one.
+---@param parent? NodeId Nil creates a root.
+---@param spec NodeSpec
+---@return NodeId
+function node.create(parent, spec) end
+
+---Adopts an existing root as a child.
+---@param parent NodeId
+---@param child NodeId Existing root without a parent.
+function node.attach(parent, child) end
+
+---Changes a node's requested size before layout.
+---@param id NodeId
+---@param w? number|"fill"|"auto"
+---@param h? number|"fill"|"auto"
+function node.setSize(id, w, h) end
+
+---Measures and places a subtree.
+---@param root NodeId
+---@param x integer
+---@param y integer
+---@param w integer
+---@param h integer
+---@return true? ok
+---@return string? error
+function node.layout(root, x, y, w, h) end
+
+---Releases temporary measurement and placement inputs after layout.
+function node.dropScratch() end
+
+---Returns the deepest interactive node under a point.
+---@param root NodeId
+---@param x integer
+---@param y integer
+---@return NodeId?
+function node.hit(root, x, y) end
+
+---Returns a node's placed rectangle.
+---@param id NodeId
+---@return integer x
+---@return integer y
+---@return integer w
+---@return integer h
+function node.getRect(id) end
+
+---Replaces a node's text and marks it for repaint.
+---@param id NodeId
+---@param text string
+function node.setLabel(id, text) end
+
+---Returns a node's text.
+---@param id NodeId
+---@return string?
+function node.getLabel(id) end
+
+---Returns a node's parent.
+---@param id NodeId
+---@return NodeId?
+function node.getParent(id) end
+
+---Sets the style roles a subtree inherits.
+---@param id NodeId
+---@param style NodeStyle
+function node.setStyle(id, style) end
+
+---Marks a node for repaint.
+---@param id NodeId
+function node.invalidate(id) end
+
+---Sets a node's pressed state.
+---@param id NodeId
+---@param pressed boolean
+function node.setPressed(id, pressed) end
+
+---Whether a node is pressed.
+---@param id NodeId
+---@return boolean
+function node.isPressed(id) end
+
+---Focuses the first interactive node in layout order.
+---@param root NodeId
+---@return NodeId? focused
+function node.focusFirst(root) end
+
+---Changes focus and invalidates the previously and newly focused nodes.
+---@param id? NodeId Nil clears focus.
+function node.setFocus(id) end
+
+---Returns the focused node.
+---@return NodeId?
+function node.getFocus() end
+
+---Moves to the nearest interactive node in the requested direction without wrapping.
+---@param root NodeId
+---@param direction NodeDirection
+---@return NodeId? focused Current focus when no candidate exists.
+function node.moveFocus(root, direction) end
+
+---Registers the painter every custom node calls.
+---@param painter fun(id: NodeId, x: integer, y: integer, w: integer, h: integer)
+function node.setPainter(painter) end
+
+---Paints dirty nodes; the firmware owns publication to the physical display.
+---@param root NodeId
+function node.draw(root) end
+
+---Returns the number of nodes in the tree.
+---@return integer
+function node.getCount() end
+
+---Returns the tree's memory use.
+---@return integer bytes
+function node.getFootprint() end

lua/api/core/runtime.lua

@@ -0,0 +1,22 @@
+---@meta
+
+-- Generated from native/src/runtime/runtime.cpp. Do not edit.
+
+-- Runtime layout:
+--   /.lua/apps/<AppId>/main.lua            application entry point
+--   /.lua/apps/<AppId>/<Subapp>/main.lua   nested route, omitted from the launcher
+--   /.lua/data/<AppId>/                    persistent app data, preserved across updates
+--   /.lua/lib/<module>.lua                 shared require() modules
+--   require() also searches the running application's directory
+--
+-- The firmware does not clear the frame before calling draw(), and commits changed
+-- display content after each callback batch using the panel's own refresh policy.
+-- Timer callbacks are registered directly with timer.after/every.
+
+---Required. Runs once before the first draw; failing here stops the app.
+---@param arg? string The string passed to sys.launch or sys.replace.
+function init(arg) end
+
+---Optional frame loop, called once after init and then at most 30 FPS, best effort.
+---@param deltaMs integer Monotonic milliseconds since the previous draw; zero on the first.
+function draw(deltaMs) end

lua/api/core/settings.lua

@@ -0,0 +1,26 @@
+---@meta
+
+-- Generated from native/src/bindings/core/settings.cpp. Do not edit.
+
+---@class SettingsLib
+settings = {}
+
+---Returns the saved rotation in degrees clockwise.
+---@return integer
+function settings.getRotation() end
+
+---Applies and persists the screen rotation.
+---@param degrees integer 0, 90, 180, or 270 clockwise.
+---@return true? ok
+---@return string? error
+function settings.setRotation(degrees) end
+
+---Returns the active POSIX timezone rule.
+---@return string
+function settings.getTimezone() end
+
+---Applies and persists a POSIX timezone rule.
+---@param timezone string
+---@return true? ok
+---@return string? error
+function settings.setTimezone(timezone) end

lua/api/core/sys.lua

@@ -0,0 +1,60 @@
+---@meta
+
+-- Generated from native/src/bindings/core/sys.cpp. Do not edit.
+
+---@alias Feature "touch"|"buttons"
+
+---@class SysLib
+sys = {}
+
+---Returns the implemented API contract version.
+---@return integer
+function sys.getAPIVersion() end
+
+---Whether the firmware implements a complete optional feature contract.
+---@param feature Feature
+---@return boolean
+function sys.hasFeature(feature) end
+
+---Returns monotonic milliseconds since boot.
+---@return integer
+function sys.getMillis() end
+
+---Returns the immutable first path component of the running app.
+---@return string
+function sys.getAppID() end
+
+---Returns the running app title, initially the app ID.
+---@return string
+function sys.getAppTitle() end
+
+---Returns the current app's guaranteed-existing persistent data directory.
+---@return string Absolute path under /.lua/data, preserved across app updates.
+function sys.getAppDataPath() end
+
+---Changes the running app's display title.
+---@param title string
+function sys.setAppTitle(title) end
+
+---Launches /.lua/apps/<path>/main.lua and pushes the current route.
+---@param path string App-relative directory path; traversal is rejected.
+---@param arg? string Passed to init(arg).
+function sys.launch(path, arg) end
+
+---Launches an app path without retaining the current route.
+---@param path string App-relative directory path; traversal is rejected.
+---@param arg? string Passed to init(arg).
+function sys.replace(path, arg) end
+
+---Returns to the previous app, or the launcher when history is empty.
+function sys.back() end
+
+---Returns heap statistics.
+---@return integer freeBytes
+---@return integer totalBytes
+---@return integer largestFreeBlock
+function sys.getMemory() end
+
+---Whether network time synchronization has completed.
+---@return boolean
+function sys.isClockSynced() end

lua/api/core/timer.lua

@@ -0,0 +1,26 @@
+---@meta
+
+-- Generated from native/src/bindings/core/timer.cpp. Do not edit.
+
+---@alias TimerId integer
+---@alias TimerCallback fun()
+
+---@class TimerLib
+timer = {}
+
+---Runs a callback once after a delay.
+---@param intervalMs integer Positive delay; callback timing is best effort and never early.
+---@param callback TimerCallback Retained until it fires or is cancelled.
+---@return TimerId
+function timer.after(intervalMs, callback) end
+
+---Runs a callback repeatedly.
+---@param intervalMs integer Positive interval; callback timing is best effort and never early.
+---@param callback TimerCallback Retained until cancelled.
+---@return TimerId
+function timer.every(intervalMs, callback) end
+
+---Cancels a timer and releases its callback.
+---@param id TimerId
+---@return boolean Whether an active timer was cancelled.
+function timer.cancel(id) end

lua/api/core/wifi.lua

@@ -0,0 +1,51 @@
+---@meta
+
+-- Generated from native/src/bindings/core/wifi.cpp. Do not edit.
+
+---@class WifiNetwork
+---@field ssid string
+---@field rssi integer
+---@field secure boolean
+
+---@alias WifiState "disconnected"|"connecting"|"connected"|"not_found"|"failed"
+
+---@class WifiStatus
+---@field state WifiState
+---@field ssid string
+---@field ip string
+---@field rssi integer
+
+---@class WifiLib
+wifi = {}
+
+---Scans for visible networks.
+---@return WifiNetwork[]? networks
+---@return string? error
+function wifi.scan() end
+
+---With credentials, saves and joins that network. Without them, reconnects saved credentials.
+---@param ssid? string
+---@param password? string Omit for an open network.
+---@return true? ok
+---@return string? error
+function wifi.connect(ssid, password) end
+
+---Returns the current connection state.
+---@return WifiStatus
+function wifi.getStatus() end
+
+---Whether the station is associated and has an address.
+---@return boolean
+function wifi.isConnected() end
+
+---Returns the station address.
+---@return string IPv4 address, or 0.0.0.0 when disconnected.
+function wifi.getLocalIP() end
+
+---Disconnects while retaining saved credentials.
+function wifi.disconnect() end
+
+---Disconnects and erases saved credentials.
+---@return true? ok
+---@return string? error
+function wifi.forget() end