The smallest plugin that runs is below. Plugin.name and function Plugin.build(ui) are required; everything else is optional. A single .lua file is a complete plugin. A .wexp package is a zip with manifest.json, main.lua, and optional lib/ and assets/ folders, nothing else.

Минимальный работающий плагин — ниже. Plugin.name и function Plugin.build(ui) обязательны, всё остальное необязательно. Один файл .lua — уже готовый плагин. Пакет .wexp — это zip с manifest.json, main.lua и необязательными папками lib/ и assets/, больше ничего.

Plugin.name = "My Plugin"

function Plugin.build(ui)
  ui:title("Hello")
end

ui is the argument of Plugin.build, not a global. Container callbacks receive their own builder (usually named c or row) which works the same way. If another function needs the top-level builder, store it in an upvalue during build.

ui — это аргумент Plugin.build, а не глобальная переменная. Колбэки контейнеров получают собственный билдер (обычно c или row), который работает так же. Если билдер верхнего уровня нужен другой функции, сохраните его в локальную переменную во время build.

local UI

function Plugin.build(ui)
  UI = ui
  ui:card(function(c)
    c:text("c is a builder too")
  end)
end

function openSecond()
  UI:push("Details", function(c) c:text("second screen") end)
end

ui:text(...) and handle:width(...) are method calls: the colon is required. Every builder returns a handle, and every style setter returns the same handle, so styling is a chain. Keep the handle in a variable when the value has to change later.

ui:text(...) и handle:width(...) — вызовы методов: двоеточие обязательно. Каждый билдер возвращает хендл, а каждый стилевой сеттер возвращает тот же хендл, поэтому оформление пишется цепочкой. Сохраняйте хендл в переменную, если значение потом должно меняться.

local out = ui:text("waiting"):color("muted"):margin("sm")
ui:button("Go", function()
  out:set("done"):color("success")
end):width("match")

There is no way to re-run build. A number that ticks is a handle you keep and call :set() on; a list that grows is ui:list with a render callback and list:count(n) to change its length. Rebuilding is what makes a plugin flicker and lose scroll position.

Перезапустить build нельзя. Меняющееся число — это сохранённый хендл, которому вы вызываете :set(); растущий список — это ui:list с колбэком render и list:count(n) для смены длины. Пересборка — причина мигания и потери позиции прокрутки.

local rows = {}
local list = ui:list({ count = 0, render = function(row, i)
  row:item({ title = rows[i].title, subtitle = rows[i].subtitle })
end })

-- later, when data arrives
rows[#rows + 1] = { title = "new", subtitle = "row" }
list:count(#rows)

The host applies a widget's initial value through the same listener a user gesture uses, so some callbacks run before the builder call has even returned its handle. Inside the constructor: ui:segmented calls fn(initial, label) every time (initial defaults to 1); ui:radio calls fn only when initial is passed; ui:bottomNav runs the initial pane's build and then onChange(initial); ui:tabs runs its builder for the initial tab. From code: :set(i) on segmented and radio, :set(bool) and :toggle() on switch and checkbox, :set(v) on a slider when the value changes, and :set(text) on input, textarea, number, password and search all invoke the callback exactly like a gesture. Silent both at creation and on :set(): chips, multiChips, dropdown, stepper, rating. Write every callback as if it can run at any moment: everything it touches — local functions, handles, tables — must already exist, or the callback checks a flag and returns. A callback that reaches a name defined further down the file fails with attempt to call nil at the callback's line, and the screen finishes building without it.

Хост применяет начальное значение виджета через тот же слушатель, что и жест пользователя, поэтому часть колбэков срабатывает ещё до того, как билдер вернул хендл. Внутри конструктора: ui:segmented вызывает fn(initial, label) всегда (initial по умолчанию 1); ui:radio вызывает fn только если передан initial; ui:bottomNav строит начальную панель и затем вызывает onChange(initial); ui:tabs запускает билдер для начальной вкладки. Из кода: :set(i) у segmented и radio, :set(bool) и :toggle() у switch и checkbox, :set(v) у слайдера при смене значения, :set(text) у input, textarea, number, password и search вызывают колбэк точно так же, как жест. Молчат и при создании, и при :set(): chips, multiChips, dropdown, stepper, rating. Пишите каждый колбэк так, будто он может сработать в любой момент: всё, к чему он обращается — локальные функции, хендлы, таблицы — должно уже существовать, либо колбэк проверяет флаг и выходит. Колбэк, который обращается к имени, определённому ниже по файлу, падает с attempt to call nil на строке колбэка, а экран достраивается без него.

• runs inside the constructorsegmented (always) · radio (when initial is given) · bottomNav onChange(initial) · tabs buildersegmented (всегда) · radio (если передан initial) · bottomNav onChange(initial) · билдер tabs
• runs on :set() / :toggle()segmented · radio · switch · checkbox · slider · input · textarea · number · password · searchsegmented · radio · switch · checkbox · slider · input · textarea · number · password · search
• never runs from codechips · multiChips · dropdown · stepper · ratingchips · multiChips · dropdown · stepper · rating

-- wrong: refresh is assigned below, so it is nil while the widget is created
ui:segmented({ "All", "Favorites" }, function(i)
  favOnly = (i == 2)
  refresh()                     -- history.lua:29 attempt to call nil
end, 1)
local function refresh() list:count(#rows) end

-- right: state and functions first, widgets second, a flag until the screen is complete
local ready, favOnly, list = false, false, nil
local function refresh()
  if not ready then return end
  list:count(#rows)
end
ui:segmented({ "All", "Favorites" }, function(i)
  favOnly = (i == 2)
  refresh()
end, 1)
list = ui:list({ count = 0, render = renderRow })
ready = true
refresh()

Every builder returns a handle. All of them share the style chain (size, margin, padding, color, bg, border, radius, alpha, visible / show / hide, enabled, onClick / onLongClick, the animations, :text(s) for anything that shows text, :bind(key), :remove()). Methods that read or change a value exist only where the reference lists them, and calling one that is not there fails with attempt to call nil: a button has :text(s) but no :set, a stepper has :set(v) but no :onChange, a kv handle points at the value column. The table below is the complete map; a widget not in it has only the shared chain.

Каждый билдер возвращает хендл. У всех есть общая цепочка стилей (размеры, margin, padding, color, bg, border, radius, alpha, visible / show / hide, enabled, onClick / onLongClick, анимации, :text(s) для всего, что показывает текст, :bind(key), :remove()). Методы, которые читают или меняют значение, есть только там, где их перечисляет справочник; вызов несуществующего метода падает с attempt to call nil: у кнопки есть :text(s), но нет :set, у stepper есть :set(v), но нет :onChange, хендл kv указывает на колонку значения. Таблица ниже — полная карта; виджет, которого в ней нет, имеет только общую цепочку.

• text · subtitle · caption · badge · kv · html · markdown:set(s) :get() :append(s) :html(s) :markdown(md) :tone(t) :copyOnTap() :link(url):set(s) :get() :append(s) :html(s) :markdown(md) :tone(t) :copyOnTap() :link(url)
• input · textarea · number · password · search:get() :set(s) :value() :number() :append(s) :clear() :isEmpty() :onChange(fn) :onSubmit(fn) :error(msg) :helper(s) :hint(s) :prefix(s) :suffix(s) :focus() :blur() :selectAll() :readonly() :maxLength(n) :type(t) :password() :lines(n) :icon(name) :clearButton() :endIcon(name, fn) :mono() :bind(key):get() :set(s) :value() :number() :append(s) :clear() :isEmpty() :onChange(fn) :onSubmit(fn) :error(msg) :helper(s) :hint(s) :prefix(s) :suffix(s) :focus() :blur() :selectAll() :readonly() :maxLength(n) :type(t) :password() :lines(n) :icon(name) :clearButton() :endIcon(name, fn) :mono() :bind(key)
• switch · checkbox:get() :set(bool) :toggle() :onChange(fn) :label(s) :bind(key):get() :set(bool) :toggle() :onChange(fn) :label(s) :bind(key)
• chips · multiChips:get() → index or {indexes} :label() :set(i | {i, …}) :clear() :items({…}) :count():get() → индекс или {индексы} :label() :set(i | {i, …}) :clear() :items({…}) :count()
• dropdown:get() :label() :set(i | "label") :items({…}) :hint(s) :error(msg) :onChange(fn):get() :label() :set(i | "label") :items({…}) :hint(s) :error(msg) :onChange(fn)
• radio · segmented:get() :label() :set(i) · radio :clear() · segmented :count():get() :label() :set(i) · radio :clear() · segmented :count()
• slider · rangeSliderslider :get() :set(v) :label(s) :format(fn) :onChange(fn) · rangeSlider :get() → { a, b } :set(a, b) :label(s)slider :get() :set(v) :label(s) :format(fn) :onChange(fn) · rangeSlider :get() → { a, b } :set(a, b) :label(s)
• stepper · ratingstepper :get() :set(v) :label(s) · rating :get() :set(v) :half() :readonly(bool)stepper :get() :set(v) :label(s) · rating :get() :set(v) :half() :readonly(bool)
• button · iconButton:text(s) :icon(name) :outlined() :tonal() :danger() :success() :loading(bool, text?) :onClick(fn(h)) :click() — no :set:text(s) :icon(name) :outlined() :tonal() :danger() :success() :loading(bool, text?) :onClick(fn(h)) :click() — без :set
• card · row · column · hscroll:clear() :rebuild(fn) :add(fn) :count() :removeAt(i) :gravity(g) :ui():clear() :rebuild(fn) :add(fn) :count() :removeAt(i) :gravity(g) :ui()
• list:count(n) :refresh() :update(i) :render(fn) :scrollTo(i) :scrollToEnd():count(n) :refresh() :update(i) :render(fn) :scrollTo(i) :scrollToEnd()
• expander · tabs · bottomNavexpander :open() :close() :toggle() :isOpen() :title(s) · tabs :select(i) :get() :refresh() · bottomNav :select(i) :current() :pane(i)expander :open() :close() :toggle() :isOpen() :title(s) · tabs :select(i) :get() :refresh() · bottomNav :select(i) :current() :pane(i)
• progress · imageprogress :set(pct) :get() :max(n) :indeterminate() :color(c) :show() :hide() · image :set(url) :fit(mode) :round(r) :circle() :tint(c) :clear()progress :set(pct) :get() :max(n) :indeterminate() :color(c) :show() :hide() · image :set(url) :fit(mode) :round(r) :circle() :tint(c) :clear()
• stat · gauge · qr · item · tilestat :set(v) :get() :label(s) :delta(text, tone) :valueColor(c) :bind(key) · gauge :set(value, label?) :label(s) :caption(s) :color(c) · qr :set(text) · item :title(s) :subtitle(s) :trailing(s) :badge(text, tone) · tile :label(s)stat :set(v) :get() :label(s) :delta(text, tone) :valueColor(c) :bind(key) · gauge :set(value, label?) :label(s) :caption(s) :color(c) · qr :set(text) · item :title(s) :subtitle(s) :trailing(s) :badge(text, tone) · tile :label(s)

local count = ui:kv("Selected", "0")             -- kv handle = the value column
local btn = ui:button("Generate", generate)
count:set("3")
btn:text("Generate 3")                           -- every text-bearing handle has :text(s)
-- btn:set("Generate 3")                         -- attempt to call nil: not a button method

local n = ui:stepper("Count", 1, 10, 3, function(v) count:set(tostring(v)) end)
n:set(5)                                         -- silent: stepper :set never calls fn
count:set("5")                                   -- so update dependants yourself

The ui passed to a container builder — ui:card / column / row / grid / hscroll / expander / tabs / stack / bottomNav, a handle's :rebuild / :add / :ui, ui:view, ui:load's render, and list / carousel / accordion rows — is the same full ui as the root. Every widget and every framework call is available on it, ui:load / ui:view / nested containers included, and what you add lands inside that container. The only exceptions are screen-level calls, which always act on the whole screen no matter which ui you use: navigation (ui:push / pop / back / close), the toolbar (ui:setTitle / setSubtitle / fab / hideFab / actions / menu / scrollTo), ui:keyboard, and the modal overlays (ui:toast / snack / dialog / alert / confirm / prompt / sheet / sheetList).

ui, переданный в билдер контейнера — ui:card / column / row / grid / hscroll / expander / tabs / stack / bottomNav, методы хендла :rebuild / :add / :ui, ui:view, render у ui:load, строки list / carousel / accordion — это тот же полный ui, что и корневой. На нём доступны все виджеты и все каркасные вызовы, включая ui:load / ui:view / вложенные контейнеры, а добавленное попадает внутрь этого контейнера. Исключение — только экранные вызовы: они всегда действуют на весь экран, каким бы ui вы ни пользовались: навигация (ui:push / pop / back / close), тулбар (ui:setTitle / setSubtitle / fab / hideFab / actions / menu / scrollTo), ui:keyboard и модальные окна (ui:toast / snack / dialog / alert / confirm / prompt / sheet / sheetList).

local results = ui:card(function(c) c:text("Loading…") end)

results:rebuild(function(c)
  -- c is a full ui: c:load works here
  c:load(function(done) Wex.http(url, done) end, function(c2, res)
    c2:list(rowsFrom(res))
  end)
end)

There is no sleep and no synchronous request. Plugin.build has four seconds and every hook has three; a loop that waits is killed by the watchdog. Network, files, devices and timers all take a function and call it back on the main thread.

Ни sleep, ни синхронных запросов нет. У Plugin.build четыре секунды, у каждого хука три; цикл ожидания убивает сторож. Сеть, файлы, устройства и таймеры принимают функцию и вызывают её на главном потоке.

Wex.http("https://api.ipify.org", function(res)
  if not res.ok then ui:toast(res.error, "error") return end
  out:set(res.body)
end)

Wex.interval(1000, function() clock:set(Wex.time.format(Wex.now(), "HH:mm:ss")) end)

io, os.execute, os.remove, os.getenv, dofile, loadfile, load, loadstring, package and debug are not there. Files go through Wex.files (the plugin's own folder) or Wex.pickFile (the user picks). Time is Wex.now and Wex.time. require works only for lib/ modules inside the package.

io, os.execute, os.remove, os.getenv, dofile, loadfile, load, loadstring, package и debug отсутствуют. Файлы — через Wex.files (папка самого плагина) или Wex.pickFile (файл выбирает пользователь). Время — Wex.now и Wex.time. require работает только для модулей из lib/ внутри пакета.

-- io.open("/sdcard/log.txt", "w")        -- does not exist
Wex.files.write("log.txt", text)          -- the plugin's own folder
local util = require("util")              -- lib/util.lua inside the package

A call whose permission is missing is refused and writes a line into the plugin log; it does not throw. Risk Check also compares the two directions and reports a permission declared but never used. Wex.can(name) tells you at runtime what was granted, since the user can revoke one after installing.

Вызов без объявленного разрешения отклоняется и пишет строку в лог плагина, исключения не будет. Risk Check дополнительно сверяет обе стороны и сообщает про объявленное, но неиспользуемое разрешение. Wex.can(имя) во время работы показывает, что выдано: пользователь может отозвать разрешение после установки.

Plugin.permissions = { "network", "bluetooth" }

if not Wex.can("bluetooth") then
  ui:banner("Bluetooth was revoked in the plugin settings", "warning")
  return
end

This is Lua 5.2 without bitwise operators, integer division or goto. A reserved word cannot be a bare table key: write ["repeat"] = true. Concatenation needs strings, so wrap numbers in tostring or use string.format. Arrays are 1-based and # gives the length.

Это Lua 5.2 без битовых операторов, целочисленного деления и goto. Зарезервированное слово нельзя использовать как ключ напрямую: пишите ["repeat"] = true. Конкатенация требует строк, поэтому оборачивайте числа в tostring или используйте string.format. Массивы нумеруются с единицы, длина — #.

Wex.ble.scan({ ["repeat"] = true, onDevice = function(d) end })
ui:text("rssi: " .. tostring(d.rssi))
ui:text(string.format("%.1f ms", rtt))

Everything that exists is listed in this reference. If a call is not here, it does not exist, and guessing produces a plugin that fails at the first tap. Wex.has(feature) and Wex.api.level exist precisely so a plugin can check instead of assuming.

Всё, что существует, перечислено в этом справочнике. Если вызова здесь нет, его нет и в системе, а догадка даёт плагин, который падает на первом нажатии. Wex.has(возможность) и Wex.api.level существуют именно для того, чтобы проверять, а не предполагать.

if Wex.has("usb") and Wex.api.level >= 7 then
  openPort()
else
  ui:caption("Update WexClient for USB")
end

Two places, two looks. If the script itself or the top-level Plugin.build throws, the screen keeps whatever was built and a red line ⚠ file:line message is appended under it; the same happens when build overruns its 4-second budget (plugin execution timed out). Everything the host calls later runs inside a guard — a tap, a selection callback, a timer, a network callback, a bottomNav or tabs pane builder, a list row renderer, the lifecycle hooks with their 3-second budget: an error there shows a red toast ⚠ file:line message with a traceback, writes ✖ message to the plugin log, abandons that one callback and leaves the plugin running. So a half-built pane plus a toast means a callback failed mid-build. The log is under Plugins → long-press → Logs, readable in code with Wex.log.lines(), and the hot-reload client tails it on the desktop. The wording is LuaJ's: attempt to call nil (a function defined further down, or a method the handle does not have), attempt to index ? (a nil value) (a handle or table that was never assigned), bad argument (wrong type). Wrap genuinely optional calls in pcall and check Wex.has / Wex.api.level instead of guessing.

Два места, два вида. Если падает сам скрипт или верхнеуровневый Plugin.build, экран сохраняет всё построенное и под ним добавляется красная строка ⚠ файл:строка сообщение; то же при превышении бюджета build в 4 секунды (plugin execution timed out). Всё, что хост вызывает позже, выполняется под защитой — тап, колбэк выбора, таймер, сетевой колбэк, билдер панели bottomNav или tabs, рендер строки списка, хуки жизненного цикла с бюджетом 3 секунды: ошибка там показывает красный тост ⚠ файл:строка сообщение с трейсбеком, пишет ✖ сообщение в лог плагина, прерывает только этот колбэк и оставляет плагин работать. Наполовину построенная панель плюс тост означают, что колбэк упал посреди сборки. Лог лежит в Плагины → долгое нажатие → Логи, читается из кода через Wex.log.lines(), а клиент hot reload показывает его на компьютере. Формулировки — от LuaJ: attempt to call nil (функция, определённая ниже, или метод, которого у хендла нет), attempt to index ? (a nil value) (хендл или таблица, которые так и не были присвоены), bad argument (не тот тип). Действительно необязательные вызовы оборачивайте в pcall и проверяйте Wex.has / Wex.api.level, а не угадывайте.

-- the toast after a failing callback:
--   ⚠ lib/screens/history.lua:29 attempt to call nil
--   stack traceback:
--     lib/screens/history.lua:29: in function 'segmented'
-- reading it: line 29 called something that was still nil at that moment

Wex.log("history built, rows=" .. tostring(#rows))     -- Plugins → long-press → Logs

local ok, cfg = pcall(function() return Wex.assets.json("presets.json") end)
if not ok then
  Wex.log.warn("presets.json missing: " .. tostring(cfg))
  cfg = {}
end

Plugin.name and Plugin.build present. Every guarded call has its permission declared, and nothing extra is declared. No loop waits for anything. Every handle whose value changes is stored in a variable. Timers, scans, ports and connections are released in Plugin.onClose. Every callback checks res.ok before reading the rest. No API name that is not in this reference. Every callback is safe to run before the rest of the screen exists.

Есть Plugin.name и Plugin.build. У каждого защищённого вызова объявлено разрешение, и ничего лишнего не объявлено. Ни один цикл ничего не ждёт. Каждый хендл с меняющимся значением сохранён в переменную. Таймеры, сканы, порты и соединения освобождаются в Plugin.onClose. Каждый колбэк проверяет res.ok перед чтением остального. Ни одного имени API, которого нет в этом справочнике. Каждый колбэк безопасно вызывать до того, как построен остальной экран.

function Plugin.onClose()
  Wex.cancelAllTimers()
  Wex.ble.stopScan()
  if port then port:close() end
end

Plugins run on LuaJ (org.luaj:luaj-jse:3.0.1) — a pure-JVM Lua 5.2 interpreter, NOT LuaJava and not a native/JNI Lua. No reflection or Java class reaches a script. The sandbox starts from LuaJ's standard globals, then strips every escape hatch: io, require, package, load/loadstring/dofile/loadfile, luajava, and the dangerous os.* (execute, exit, remove, rename, tmpname, getenv, setlocale); the debug table is hidden. A per-instruction debug hook enforces a wall-clock timeout, so a runaway loop is interrupted instead of freezing the app. Everything a plugin can reach comes through the Wex and ui tables — nothing else.

Плагины исполняются на LuaJ (org.luaj:luaj-jse:3.0.1) — чистом JVM-интерпретаторе Lua 5.2, НЕ LuaJava и не нативном/JNI-Lua. Ни рефлексии, ни Java-классов скрипту недоступно. Песочница берёт стандартные globals LuaJ и срезает все лазейки: io, require, package, load/loadstring/dofile/loadfile, luajava и опасные os.* (execute, exit, remove, rename, tmpname, getenv, setlocale); таблица debug скрыта. Per-instruction debug-хук держит настенный таймаут, поэтому зациклившийся код прерывается, а не вешает приложение. Всё, до чего дотягивается плагин, идёт через таблицы Wex и ui — и только через них.

-- these are NOT available inside a plugin (stripped by the sandbox):
-- io, require, package, load, loadstring, dofile, loadfile, luajava,
-- os.execute, os.exit, os.remove, os.rename, os.getenv, debug
print(os.time(), os.date("%H:%M"))   -- safe os.* stays

Every plugin run gets its OWN fresh Globals: its own Lua state, its own copy of the standard library, its own global table. Plugins never share a Lua state, so one plugin cannot read or overwrite another's globals, functions or upvalues. Shared code loaded with Wex.import runs in a child environment whose reads fall through to the importer's globals but whose writes stay local — shared code, not shared authority. The only cross-plugin channel is explicit and data-only: Wex.bus.

Каждый запуск плагина получает СВОЙ свежий Globals: свой lua-state, свою копию стандартной библиотеки, свою таблицу globals. Плагины никогда не делят lua-state, поэтому один плагин не может прочитать или перезаписать globals, функции или upvalue другого. Общий код через Wex.import выполняется в дочернем окружении: чтения проваливаются в globals импортёра, а записи остаются локальными — общий код, но не общие полномочия. Единственный межплагинный канал — явный и только для данных: Wex.bus.

local util = Wex.import("acme.util")   -- runs in a child env: sees your globals,
                                       -- but its own writes never leak into yours
Wex.bus.emit("track", { id = 7 })      -- the only cross-plugin channel (data only)

ui:* builds real Android Views — the platform widgets and Material Components (LinearLayout, MaterialCardView, MaterialButton, RecyclerView, WebView, …) — not a Compose tree and not an HTML shim. Each builder returns a handle: a Lua table wrapping the View, carrying the shared style chain (size, color, margin, padding, radius, alpha, visibility, animations, :bind, :remove) plus that widget's own methods. All UI construction and mutation runs on the Android main thread; anything slow you start (http, image, folder, io) runs on a background executor and calls you back on the main thread.

ui:* строит настоящие Android View — системные виджеты и Material Components (LinearLayout, MaterialCardView, MaterialButton, RecyclerView, WebView, …), а не дерево Compose и не HTML-обёртку. Каждый билдер возвращает хендл: lua-таблицу поверх View с общей цепочкой стилей (размеры, цвет, margin, padding, radius, alpha, видимость, анимации, :bind, :remove) плюс методами самого виджета. Всё построение и изменение UI идёт в главном потоке Android; всё медленное, что вы запускаете (http, image, folder, io), уходит на фоновый executor и возвращается колбэком в главный поток.

local card = ui:card()              -- a MaterialCardView
local btn  = ui:button("Go")        -- a MaterialButton, returned as a handle
btn:bg("#2563EB"):radius(12):onClick(function() ui:toast("hi") end)

Permissions are not honour-based. Before every sensitive call the Kotlin bridge checks the plugin's DECLARED capabilities (needs("network", …)) and refuses with a readable error if it was never declared — the Lua side cannot bypass this. Capabilities that map to an OS runtime permission (camera, microphone, location, contacts, calendar, bluetooth, …) pass a second gate: RuntimePerms.ensure runs immediately if already granted, otherwise asks the user through the host and reports a denial back to the plugin's error channel. So a sensitive call needs BOTH: declared in the manifest AND granted by the OS/user.

Разрешения не на доверии. Перед каждым чувствительным вызовом Kotlin-мост проверяет ОБЪЯВЛЕННЫЕ возможности плагина (needs("network", …)) и отказывает с читаемой ошибкой, если оно не объявлено — со стороны Lua это не обойти. Возможности, отображаемые на системное разрешение (камера, микрофон, геолокация, контакты, календарь, bluetooth, …), проходят второй гейт: RuntimePerms.ensure срабатывает сразу, если уже выдано, иначе спрашивает пользователя через хост и сообщает об отказе в канал ошибок плагина. Значит, чувствительному вызову нужно И объявление в манифесте, И согласие ОС/пользователя.

-- Without Plugin.permissions = { "network" } this line fails with:
--   "Wex.http blocked — declare Plugin.permissions = {\"network\"}"
Wex.http({ url = "https://api.example.com" }, function(res) end)

When a plugin screen closes, Plugin.onClose() runs, then the bridge disposes everything transient: timers (every/after/interval) cancelled; open sockets / websockets / TCP / UDP closed; DB handles closed; sensor and location listeners unregistered; audio / TTS / mic / speech / torch / media released; Wex.bus subscriptions removed. In-flight async work is neutralised, not awaited — a disposed flag turns every Lua callback into a no-op, so a late HTTP or download result arriving after close never runs plugin code (and a partial download file is deleted). Persistent state SURVIVES: Wex.storage, Wex.secure, Wex.cache, the plugin DB, files, and granted folders. Transient in-memory state is released with the Lua state for the GC; reopening the plugin starts a brand-new Lua state.

Когда экран плагина закрывается, выполняется Plugin.onClose(), затем мост освобождает всё временное: таймеры (every/after/interval) отменяются; открытые сокеты / websocket / TCP / UDP закрываются; хендлы БД закрываются; слушатели сенсоров и геолокации снимаются; audio / TTS / микрофон / речь / фонарик / media освобождаются; подписки Wex.bus удаляются. Асинхронная работа в полёте гасится, а не дожидается — флаг disposed превращает каждый Lua-колбэк в no-op, поэтому поздний результат HTTP или загрузки, пришедший после закрытия, не выполнит код плагина (а частично скачанный файл удаляется). Постоянное состояние ПЕРЕЖИВАЕТ закрытие: Wex.storage, Wex.secure, Wex.cache, БД плагина, файлы и выданные папки. Временное состояние в памяти освобождается вместе с lua-state под GC; повторное открытие плагина стартует совершенно новый lua-state.

function Plugin.onClose()
  -- last chance to persist; runs BEFORE the bridge tears timers/sockets down
  Wex.storage.set("draft", editor:text())
end
-- an http() still in flight here will simply never call back (disposed = no-op)

Risk Check compares what the manifest declares against what the code calls, and reports both directions: a permission you declared but never use looks careless, and a call without its permission is refused at runtime with an error in the log. Add a permission when you add the call, not before.

Risk Check сверяет объявленное в манифесте с тем, что вызывает код, и сообщает про оба перекоса: объявленное, но неиспользуемое разрешение выглядит небрежно, а вызов без разрешения будет отклонён во время работы с ошибкой в логе. Добавляйте разрешение вместе с вызовом, а не заранее.

Plugin.permissions = { "network" }   -- and nothing else until you need it

if not Wex.can("network") then
  ui:banner("Offline", "warning")
  return
end

Plugin.build has four seconds and every hook has three; a loop that waits for something kills the screen instead of waiting. There is no sleep in the sandbox on purpose. Anything slow is a callback: Wex.http, Wex.timer, Wex.interval, the BLE and USB handlers.

У Plugin.build есть четыре секунды, у каждого хука — три; цикл ожидания не ждёт, а убивает экран. Функции sleep в песочнице нет намеренно. Всё медленное — это колбэк: Wex.http, Wex.timer, Wex.interval, обработчики BLE и USB.

-- wrong: freezes the screen and gets killed by the watchdog
-- while not done do end

-- right
Wex.interval(1000, function()
  status:set(Wex.time.now())
end)

Turning the phone destroys and rebuilds the screen, and your locals go with it. What must survive belongs in Wex.state (kept across a hot reload too) or in Wex.storage (kept across restarts). The host restores full-screen mode and the rotation lock before your first frame, so do not re-apply them in build.

Поворот телефона уничтожает и пересобирает экран, локальные переменные исчезают вместе с ним. То, что должно пережить это, живёт в Wex.state (переживает и hot reload) или в Wex.storage (переживает перезапуск). Полноэкранный режим и блокировку ориентации хост восстановит до первого кадра сам, повторно применять их в build не нужно.

function Plugin.onPause()
  Wex.storage.set("draft", input:value())
end

function Plugin.build(ui)
  local draft = Wex.storage.get("draft") or ""
  input = ui:field({ value = draft })
end

Timers, BLE scans and connections, USB ports, RFCOMM links, sensors and the NFC reader all keep running until something stops them. The host disposes the bridge when the screen goes away, but a plugin that stops its own work behaves predictably during a hot reload and while the screen is merely paused.

Таймеры, сканы и подключения BLE, USB-порты, каналы RFCOMM, датчики и считыватель NFC работают, пока их не остановят. Хост освобождает мост при уходе с экрана, но плагин, который останавливает свою работу сам, ведёт себя предсказуемо и при hot reload, и когда экран просто на паузе.

function Plugin.onClose()
  Wex.cancelAllTimers()
  Wex.ble.stopScan()
  Wex.sensors.stopAll()
  if port then port:close() end
end

Most phones have no infrared blaster, many have no NFC, and USB host mode is not universal. Every hardware namespace answers available() without asking for anything, so branch on it and show a clear empty state instead of failing silently.

У большинства телефонов нет инфракрасного передатчика, у многих нет NFC, а режим USB-host есть не везде. Каждое аппаратное пространство имён отвечает на available() ничего не запрашивая, поэтому ветвитесь по нему и показывайте понятную заглушку вместо тихого отказа.

if not Wex.ir.available() then
  ui:empty("info", "No IR blaster", "This phone cannot send infrared")
  return
end

A plugin installed on an older build must degrade, not crash. minApi in the manifest stops the install outright; Wex.api.level and Wex.has(feature) let one plugin work on both. Hardware arrived at level 7, share targets and hot reload at level 6.

Плагин, установленный на старую сборку, должен деградировать, а не падать. Поле minApi в манифесте запрещает установку совсем; Wex.api.level и Wex.has(feature) позволяют одному плагину работать и там и там. Работа с железом появилась на уровне 7, приём «Поделиться» и hot reload — на уровне 6.

if Wex.api.level >= 7 and Wex.has("usb") then
  openSerial()
else
  ui:caption("Update WexClient for USB support")
end

Network, file and device results carry ok and error, and reading a field of a failed result is how a plugin ends up showing nil. Check ok first; it costs one line and turns a crash into a message.

Результаты сети, файлов и устройств несут ok и error, а чтение поля неудачного результата — это как раз то, из-за чего плагин показывает nil. Проверяйте ok первым: одна строка превращает падение в сообщение.

Wex.http("https://example.com/api", function(res)
  if not res.ok then
    ui:toast(res.error or "request failed", "error")
    return
  end
  render(res.json)
end)

Wex.ir.repeat would be a parse error, which is why that call is named resend and the Pronto result field is repeatPattern. If you ever need a reserved name on a table, index it with brackets.

Wex.ir.repeat — это синтаксическая ошибка, поэтому вызов называется resend, а поле результата Pronto — repeatPattern. Если зарезервированное имя в таблице всё же нужно, обращайтесь через скобки.

Wex.ir.resend({ protocol = "nec", address = 0x04, command = 0x08 }, 3, 40)
local alias = Wex.ir["repeat"]  -- the same function, awkward spelling

A render callback creates rows as they scroll into view; a for loop over a thousand items creates a thousand views before the first frame. The same applies to charts: push points into an existing handle instead of rebuilding the screen.

Колбэк render создаёт строки по мере прокрутки; цикл for по тысяче элементов создаёт тысячу View до первого кадра. То же с графиками: добавляйте точки в существующий хендл, а не пересобирайте экран.

ui:list({ count = #items, render = function(row, i)
  row:item({ title = items[i].name, subtitle = items[i].ip })
end })

margin, padding, gap and radius accept xs, sm, md, lg, xl and xxl. Screens built from tokens share one rhythm, survive a design change, and give an assistant a vocabulary to reuse instead of inventing numbers.

margin, padding, gap и radius принимают xs, sm, md, lg, xl и xxl. Экраны, собранные на токенах, имеют общий ритм, переживают смену дизайна и дают ассистенту готовый словарь вместо выдуманных чисел.

ui:card(function(c)
  c:kv("Host", host)
end, "sm"):margin("md")

A package can carry lib/name.lua files that require("name") loads, and assets/ files that ship with the plugin. One 2000-line main.lua is hard to review, hard for an assistant to edit and impossible to reuse.

Пакет может нести файлы lib/name.lua, которые загружает require("name"), и файлы assets/, которые едут вместе с плагином. Один main.lua на две тысячи строк тяжело читать, тяжело править ассистентом и невозможно переиспользовать.

-- lib/net.lua
local M = {}
function M.ping(host, cb) Wex.net.ping(host, cb) end
return M

-- main.lua
local net = require("net")

ui:html and ui:web render what you give them. Anything that came from the network, a file, an NFC tag or a serial port is untrusted; pass it through Wex.str.escapeHtml or put it in a plain ui:text, which never interprets markup.

ui:html и ui:web отображают то, что им дали. Всё, что пришло из сети, файла, NFC-метки или последовательного порта — недоверенное; пропускайте это через Wex.str.escapeHtml или показывайте обычным ui:text, который разметку не интерпретирует.

ui:text(res.body)                       -- safe
ui:html(Wex.str.escapeHtml(res.body))   -- safe
-- ui:html(res.body)                    -- not safe

The editor can start a small HTTP server on your Wi-Fi and re-run the preview after every save from VS Code, Zed or Neovim, keeping Wex.state across reloads. The same menu exports wex-api.def.lua, which gives the Lua Language Server full completion for ui, Wex and Plugin.

Редактор поднимает небольшой HTTP-сервер в вашей сети и перезапускает предпросмотр после каждого сохранения из VS Code, Zed или Neovim, сохраняя Wex.state между перезапусками. Это же меню экспортирует wex-api.def.lua, который даёт Lua Language Server полное автодополнение по ui, Wex и Plugin.

# on the computer, Node 18+, nothing to install
node wex-dev.mjs "http://192.168.1.20:8765/?token=abcd2345" ./my-plugin

An icon or a data file inside assets/ works offline, needs no network permission and cannot change under you. Download at runtime only what genuinely has to be fresh.

Иконка или файл данных внутри assets/ работает офлайн, не требует разрешения на сеть и не может подмениться. Скачивайте во время работы только то, что действительно должно быть свежим.

ui:image("asset:logo.png"):width(120)
local cfg = Wex.assets.readJson("defaults.json")

The id decides what an update replaces; the version decides whether the app offers the update at all. Changing the id publishes a second, unrelated plugin and orphans the user's data and granted permissions.

Идентификатор решает, что именно заменит обновление; версия решает, предложит ли приложение обновление вообще. Смена идентификатора публикует второй, никак не связанный плагин и оставляет данные и выданные разрешения пользователя сиротами.

Plugin.id = "ip_info"      -- never changes
Plugin.version = "1.3"     -- goes up with every release

margin / padding / gap / radius all accept "xs"(4) / "sm"(8) / "md"(12) / "lg"(16) / "xl"(24) / "xxl"(32) — or "full" for radius — instead of a raw dp number. Every screen then shares one rhythm, and a script pasted into an AI has a vocabulary to reuse instead of inventing new numbers each time.

margin / padding / gap / radius принимают "xs"(4) / "sm"(8) / "md"(12) / "lg"(16) / "xl"(24) / "xxl"(32) — или "full" для radius — вместо произвольного dp. Тогда у всех экранов один ритм, а у вставленного в ИИ скрипта есть готовый словарь вместо новых чисел каждый раз.

ui:card(f):padding("lg"):radius("md")
ui:spacer("sm")

Pass gap as the 2nd argument to ui:row / ui:column / ui:card instead of :marginStart()/:marginEnd() on every child — one number, applied evenly, nothing forgotten on the first or last item.

Передавай gap вторым аргументом в ui:row / ui:column / ui:card вместо :marginStart()/:marginEnd() на каждом ребёнке — одно число, применяется равномерно, ничего не забыто у первого/последнего элемента.

ui:row(function(c)
  c:button("A", f):grow()
  c:button("B", f):grow()
end, "md")

A card (or a row of cards) reads as one idea. Avoid nesting more than ~2 containers deep — flatten with sibling row/column calls instead of boxes inside boxes inside boxes.

Карточка (или ряд карточек) читается как одна мысль. Не вкладывай больше ~2 контейнеров — используй соседние row/column вместо коробок в коробках.

title / subtitle / text / caption already encode the type scale (20/16/14/11sp). Drop to :textSize()/:color() only for a genuine one-off accent, not for routine headings.

title / subtitle / text / caption уже задают шкалу типографики (20/16/14/11sp). К :textSize()/:color() обращайся только для настоящего разового акцента, не для обычных заголовков.

ui:badge(text, tone) is legible in both themes by construction — a hand-picked hex text color usually isn't once the user flips theme.

ui:badge(text, tone) по построению читаем в обеих темах — ручной hex-цвет текста обычно перестаёт быть читаемым при смене темы.

title + a card of kv rows + a badge for state + one action button. A complete, consistent screen in a dozen lines, built entirely from the primitives above.

title + карточка со строками kv + бейдж состояния + одна кнопка действия. Цельный, согласованный экран в десяток строк — целиком из примитивов выше.

function Plugin.build(ui)
  ui:title("Tunnel")
  ui:card(function(c)
    c:row(function(r)
      r:subtitle("Status"):grow()
      r:badge("connected", "success")
    end)
    c:kv("Endpoint", "10.0.4.1:51820")
    c:kv("Latency", "23 ms")
    c:kv("Data", "128 MB ↓ · 9 MB ↑")
  end, "sm")
  ui:spacer("md")
  ui:button("Disconnect", function()
    Wex.confirm({ title = "Disconnect?" }, function(ok)
      if ok then ui:toast("disconnected") end
    end)
  end):width("match")
end

Check the data first and show ui:empty instead of a blank card — a list with zero rows is a state to design for, not a bug to ignore.

Сначала проверь данные и покажи ui:empty вместо пустой карточки — список из нуля строк — это состояние для дизайна, а не баг, который можно игнорировать.

if #items == 0 then
  ui:empty("info", "No scans yet", "Run a scan to see results here")
else
  ui:list({ count = #items,
    render = function(row, i) row:kv(items[i].name, items[i].ip) end })
end

ui:theme() returns the whole system: { dark, color = { primary, surface, onSurface, onSurfaceVariant, success, warning, danger, info, … }, space, radius, type, motion }. Shortcuts: ui:color("primary") → "#RRGGBB", ui:space("lg") → 16, ui:radius("md"), ui:type("title"), ui:dark() → bool. Use the same tokens the widgets use when you draw a canvas, colour a chart or branch on the theme — nothing hard-coded, and it follows light/dark automatically.

ui:theme() возвращает всю систему: { dark, color = { primary, surface, onSurface, onSurfaceVariant, success, warning, danger, info, … }, space, radius, type, motion }. Короткие формы: ui:color("primary") → "#RRGGBB", ui:space("lg") → 16, ui:radius("md"), ui:type("title"), ui:dark() → bool. Бери те же токены, что и виджеты, когда рисуешь canvas, красишь график или ветвишься по теме — ничего не захардкожено, и всё само подстраивается под светлую/тёмную.

Put custom fonts (.ttf/.otf) and images in your plugin’s assets/ folder, then apply them anywhere: :font("assets/fonts/Manrope.ttf") on any text handle, and :bgImage("assets/bg.png", { fit, radius, overlay }) on cards, rows and most views. One package carries its own look, works offline, and stays consistent across screens.

Сложи свои шрифты (.ttf/.otf) и картинки в папку assets/ плагина и применяй где угодно: :font("assets/fonts/Manrope.ttf") на любом текстовом хендле и :bgImage("assets/bg.png", { fit, radius, overlay }) на карточках, рядах и большинстве вью. Один пакет несёт свой вид, работает оффлайн и выглядит одинаково на всех экранах.

For anything that changes, prefer ui:view over hand-held handles. Put the truth in Wex.state, describe the screen inside the view, and set state to change it — the container re-renders itself. Reach for :show()/:hide()/:set() only for a single widget you are updating in a tight loop (a counter, a progress bar), where a full rebuild would be wasteful.

Всё, что меняется, лучше описывать через ui:view, а не держать пачку хендлов. Держи истину в Wex.state, описывай экран внутри view и меняй состояние — контейнер перерисуется сам. Ручные :show()/:hide()/:set() оставь для одиночного виджета, который обновляешь часто (счётчик, прогресс), где полная пересборка была бы лишней.

The manifest — plain fields you assign at the top of the script.

Манифест — простые поля, которые ты задаёшь вверху скрипта.

• nametitle in the plugin list and the menu.заголовок в списке плагинов и в меню.
• iconan emoji, shown as the tile/menu icon.эмодзи, показывается как иконка плитки/меню.
• descriptionone line under the name on the card.одна строка под названием на карточке.

Plugin.name = "IP Info"
Plugin.icon = "🌐"
Plugin.description = "Look up an IP"

Optional metadata shown under the name and used for update detection.

Необязательные данные под именем; используются для детекта обновлений.

• versione.g. "1.2" — compared numerically when re-installing.напр. "1.2" — сравнивается численно при переустановке.
• authoryour name; shown as the credited author.твоё имя; показывается как автор.

Plugin.version = "1.0"
Plugin.author = "you"

Wex.api.level rises as the platform gains features; manifest.minApi is the lowest level your plugin needs — older apps refuse to install instead of crashing. 5 — full-screen play mode, orientation, ui:web. 6 — share targets (Plugin.handles) and desktop hot reload. 7 — hardware: Wex.ir / nfc / usb / bt / wifi. 8 — Wex.ok / err result guards, storage schema migrations, Wex.apiLevel. 9 — library plugins (Plugin.provides / exports, Wex.import), the cross-plugin Wex.bus, Plugin.settings, and expressive widgets (ui:splitButton, ui:wavyProgress, ui:floatingToolbar). 10 — the Expressive motion system: :spring physics, :shape / :shapeMorph, :glass / :blur, :shared container-transform on ui:push, and predictive back (Plugin.onBackPredictive), and the ui:scaffold screen chrome (collapsing large title, FAB, pull-to-refresh). 11 — media & device: Wex.image processing, ui:video, Wex.torch. 12 — reactive SQLite (db:live/onChange), a fused compass (Wex.sensors.orientation), streamed download progress/cancel. 13 — exact alarms (Wex.alarm) and on-device speech recognition (Wex.audio.listen). 14 — read-only content providers: the address book (Wex.contacts) and the agenda (Wex.calendar). 15 — a still photo from the system camera app (Wex.camera.capture). 16 — durable folder access: pick a folder once, read and write inside it across runs (Wex.folder). 17 — structured WebView RPC: a ui:web page calls Wex.call(method, args) and Lua answers with w:handle. 18 — launch another app for its result (Wex.intent.startForResult). 19 — binary read/write in a granted folder (folder:read / folder:write). 20 — biometric / device-credential auth gate (Wex.auth.biometric). 21 — background media session with lock-screen / notification transport controls (Wex.media). 22 (WexClient Next) — declarative binary-packet synthesis & parse DSL (Wex.packet). 23 — typed schema-validated service RPC across plugins with semver discovery (Wex.bus.provide/discover/call). 24 — composable DSP pipeline over the primitives (Wex.dsp.graph). 25 — declarative plug-and-play USB device drivers (Wex.driver). 26 — wex-pm: versioned semantic imports, Wex.import(name, semverRange). 27 — unified privilege: root (Wex.su) and Shizuku shell (Wex.shizuku), consented and audited. 28 — distributed cross-plugin state with HLC/LWW convergence (Wex.bus.state). 29 — an aspect-oriented action pipeline: observe/transform/intercept/replace/fire (Wex.hook). 30 — zero-lag reconciliation: ui:view coalesces state-driven rebuilds to one per display frame. Anything above your minApi must be guarded with Wex.api.level or Wex.has(feature).

Wex.api.level растёт по мере появления возможностей; manifest.minApi — минимальный нужный уровень, старое приложение откажется устанавливать, а не упадёт. 5 — полноэкранный режим, ориентация, ui:web. 6 — цели «Поделиться» (Plugin.handles) и hot reload с компьютера. 7 — железо: Wex.ir / nfc / usb / bt / wifi. 8 — стражи результата Wex.ok / err, миграции схемы storage, Wex.apiLevel. 9 — библиотечные плагины (Plugin.provides / exports, Wex.import), межплагинная шина Wex.bus, Plugin.settings и экспрессивные виджеты (ui:splitButton, ui:wavyProgress, ui:floatingToolbar). 10 — выразительная система движения: :spring-физика, :shape / :shapeMorph, :glass / :blur, :shared container-transform на ui:push и предиктивный back (Plugin.onBackPredictive) и chrome экрана ui:scaffold (схлопывающийся крупный заголовок, FAB, pull-to-refresh). 11 — медиа и устройство: обработка Wex.image, ui:video, Wex.torch. 12 — реактивный SQLite (db:live/onChange), слитый компас (Wex.sensors.orientation), загрузка потоком с прогрессом/отменой. 13 — точные будильники (Wex.alarm) и распознавание речи на устройстве (Wex.audio.listen). 14 — контент-провайдеры только для чтения: адресная книга (Wex.contacts) и календарь (Wex.calendar). 15 — снимок через системную камеру (Wex.camera.capture). 16 — постоянный доступ к папке: выдать папку один раз, читать и писать в ней между запусками (Wex.folder). 17 — структурный WebView-RPC: страница ui:web вызывает Wex.call(method, args), Lua отвечает через w:handle. 18 — запуск другого приложения ради результата (Wex.intent.startForResult). 19 — бинарные чтение/запись в выданной папке (folder:read / folder:write). 20 — биометрия / учётные данные устройства как гейт (Wex.auth.biometric). 21 — фоновая медиасессия с управлением на экране блокировки / в шторке (Wex.media). 22 (WexClient Next) — декларативный DSL синтеза и разбора бинарных пакетов (Wex.packet). 23 — типизированный RPC сервисов между плагинами со схемой и semver-discovery (Wex.bus.provide/discover/call). 24 — компонуемый DSP-конвейер поверх примитивов (Wex.dsp.graph). 25 — декларативные plug-and-play USB-драйверы устройств (Wex.driver). 26 — wex-pm: версионные семантические импорты, Wex.import(name, semverRange). 27 — единая привилегия: root (Wex.su) и shell через Shizuku (Wex.shizuku), с согласием и аудитом. 28 — распределённое межплагинное состояние с HLC/LWW-сходимостью (Wex.bus.state). 29 — аспектно-ориентированный конвейер действий: observe/transform/intercept/replace/fire (Wex.hook). 30 — zero-lag reconciliation: ui:view коалесцирует перестройки по состоянию до одной на кадр. Всё, что выше вашего minApi, нужно защищать через Wex.api.level или Wex.has(feature).

if Wex.api.level >= 9 then
  local lib = Wex.import("crypto_utils")
end
if Wex.has("wavyProgress") then ui:wavyProgress({ value = 30 }) end

Array of sensitive capabilities the plugin needs. Anything not listed is blocked.

Массив чувствительных возможностей, которые нужны плагину. Что не указано — заблокировано.

• "network"Wex.http / websocket / download / upload / ui:image.Wex.http / websocket / download / upload / ui:image.
• "files"Wex.pickFile / saveFile (the user's real files).Wex.pickFile / saveFile (настоящие файлы пользователя).
• "notifications"Wex.notifications.Wex.notifications.
• "background"Wex.background periodic task.периодическая задача Wex.background.

Plugin.permissions = { "network", "notifications" }

Makes the plugin a Share target: MIME patterns it accepts from the system Share sheet (a link, text, photos, documents, several files at once). The user picks the plugin in the sheet (each handler is its own row) or in a chooser; files are copied into the plugin's own folder and the plugin opens with Wex.args.share. No permission needed — the user chose you.

Делает плагин целью «Поделиться»: MIME-шаблоны, которые он принимает из системного меню (ссылка, текст, фото, документы, несколько файлов сразу). Пользователь выбирает плагин прямо в меню (каждый обработчик — отдельная строка) или в списке; файлы копируются в папку плагина, и он открывается с Wex.args.share. Разрешение не нужно — пользователь выбрал вас сам.

• "text/plain"shared text and links (Wex.args.share.text).текст и ссылки (Wex.args.share.text).
• "image/*"any image; "*/*" accepts everything, "application/pdf" one exact type.любое изображение; "*/*" — всё подряд, "application/pdf" — один точный тип.

Plugin.handles = { "text/plain", "image/*" }

function Plugin.build(ui)
  local s = Wex.args.share
  if s and s.text then ui:text(s.text) end
  for _, f in ipairs(s and s.files or {}) do
    ui:image(f.name)  -- already a file in Wex.files
  end
end

Entry point that builds the screen. Runs on the main thread each time the plugin opens.

Точка входа, строит экран. Выполняется в главном потоке при каждом открытии плагина.

• uithe builder — call ui:title, ui:button, … on it.билдер — вызывай на нём ui:title, ui:button, …

returnsвозвращаетnothing — you build the UI by side effect.ничего — интерфейс строится побочным эффектом.

function Plugin.build(ui)
  ui:title("Hello")
  ui:text("Ready.")
end

Optional headless task run on a schedule (see Wex.background). No `ui` — only the `Wex` global.

Необязательная фоновая задача по расписанию (см. Wex.background). Без `ui` — только глобальный `Wex`.

function Plugin.background()
  Wex.http("https://…", function(res) end)
end

Turn a plugin into a library other plugins reuse. Plugin.provides lists the API name(s) this plugin publishes; Plugin.exports() returns the table of functions under those names. A consumer lists Plugin.requires and pulls the table in with Wex.import(name). A pure library has exports and no Plugin.build — it never shows a screen. Imported code runs inside the caller's sandbox with the caller's permissions, so importing a library never grants extra power.

Превращает плагин в библиотеку, которую переиспользуют другие. Plugin.provides перечисляет имя(имена) API, которое плагин публикует; Plugin.exports() возвращает таблицу функций под этими именами. Потребитель указывает Plugin.requires и получает таблицу через Wex.import(name). Чистая библиотека имеет exports и не имеет Plugin.build — у неё нет своего экрана. Импортированный код выполняется в песочнице вызывающего с его разрешениями, поэтому импорт библиотеки не даёт лишних прав.

-- library plugin (no Plugin.build)
Plugin.name = "Text utils"
Plugin.provides = { "text_utils" }
function Plugin.exports()
  return { shout = function(s) return s:upper() .. "!" end }
end

-- consumer plugin
Plugin.requires = { "text_utils" }
local text = Wex.import("text_utils")

Optional contribution: when defined, the host shows a ⚙ action in the toolbar that opens a dedicated settings screen built by this function. Same ui builder as Plugin.build, on its own pushed screen.

Необязательная точка расширения: если задана, хост показывает действие ⚙ в тулбаре, открывающее отдельный экран настроек, который строит эта функция. Тот же билдер ui, что и в Plugin.build, на отдельном экране.

function Plugin.settings(ui)
  ui:title("Settings")
  ui:switch("Dark mode", Wex.storage.get("dark") == "1", function(on)
    Wex.storage.set("dark", on and "1" or "0")
  end)
end

A plugin is a zip with the .wexp extension. main.lua is the entry point (unchanged from single-file plugins); lib/ holds modules for require(); assets/ holds any files — png, jpg, mp3, wav, json, xml, csv, html, fonts. Single-file .lua plugins keep working: they are wrapped into the same layout on install.

Плагин — это zip с расширением .wexp. main.lua — точка входа (как у одиночных плагинов); в lib/ лежат модули для require(); в assets/ — любые файлы: png, jpg, mp3, wav, json, xml, csv, html, шрифты. Одиночные .lua продолжают работать: при установке они оборачиваются в ту же структуру.

my_plugin.wexp
├─ manifest.json
├─ main.lua
├─ lib/utils.lua
└─ assets/logo.png

Written by the editor from Plugin.* fields when you don't write one yourself. icon is an emoji or a package path like "assets/icon.png" (used in lists and on the forum). minApi = the Wex.api.level your plugin needs — older apps refuse to install instead of crashing. runtime is "lua".

Редактор генерирует его из полей Plugin.*, если вы не написали свой. icon — эмодзи или путь внутри пакета вроде "assets/icon.png" (показывается в списках и на форуме). minApi — нужный Wex.api.level: старое приложение откажется устанавливать, а не упадёт. runtime — "lua".

{ "name": "Radar", "version": "1.2", "icon": "assets/icon.png",
  "permissions": ["network"], "minApi": 3 }

Loads lib/name.lua (dots map to folders: require("net.http") → lib/net/http.lua or lib/net/http/init.lua). Cached per run; a module returning nothing yields true. Only the package's own lib/ is reachable.

Загружает lib/name.lua (точки — папки: require("net.http") → lib/net/http.lua или lib/net/http/init.lua). Кэшируется на запуск; модуль без return даёт true. Доступен только lib/ своего пакета.

-- lib/utils.lua
local M = {}
function M.fmt(ms) return Wex.format.duration(ms) end
return M

-- main.lua
local utils = require("utils")

Load the public API of the library plugin that declared Plugin.provides = { name } and return its Plugin.exports() table. The result is cached, so a name is a singleton per run (like require). The library runs in this plugin's sandbox with this plugin's permissions — shared code, not shared authority. Returns nil (with a logged error) when no enabled plugin provides name (a disabled provider is not resolved), on a dependency cycle, or on a self-import. Works in the foreground and in background jobs. Plugin.exports may be a function (called) or a table (used as-is).

Загружает публичный API библиотечного плагина, объявившего Plugin.provides = { name }, и возвращает его таблицу Plugin.exports(). Результат кэшируется, поэтому имя — синглтон на запуск (как require). Библиотека выполняется в песочнице этого плагина с его разрешениями — общий код, а не общие права. Возвращает nil (с записью в лог), если ни один включённый плагин не предоставляет name (выключенный провайдер не резолвится), при цикле зависимостей или импорте самого себя. Работает на переднем плане и в фоновых задачах. Plugin.exports может быть функцией (вызывается) или таблицей (используется как есть).

local text = Wex.import("text_utils")
if text then ui:text(text.shout("hi")) end

The versioned form of Wex.import (a wex-pm slice): pass a semantic-version range as the second argument and the import binds only if the installed provider's version satisfies it — otherwise it fails loudly (returns nil and reports an error) instead of silently binding an incompatible library. Ranges: exact "1.2.3", caret "^2.3.0" (>=2.3.0 <3.0.0; for 0.x, ^0.2.3 means >=0.2.3 <0.3.0), tilde "~1.2.0" (>=1.2.0 <1.3.0), comparators and space-separated conjunctions ">=1.0 <2.0", or "*" / omitted for any version. The provider's version is its Plugin.version (manifest version). Pair it with Plugin.requires to pin a compatible dependency.

Версионная форма Wex.import (срез wex-pm): передай semver-диапазон вторым аргументом, и импорт свяжется только если версия установленного провайдера ему удовлетворяет — иначе он падает явно (возвращает nil и сообщает об ошибке), а не связывает молча несовместимую библиотеку. Диапазоны: точная "1.2.3", caret "^2.3.0" (>=2.3.0 <3.0.0; для 0.x, ^0.2.3 значит >=0.2.3 <0.3.0), tilde "~1.2.0" (>=1.2.0 <1.3.0), сравнения и конъюнкции через пробел ">=1.0 <2.0", или "*" / без аргумента — любая версия. Версия провайдера — это его Plugin.version (версия манифеста). Сочетай с Plugin.requires, чтобы закрепить совместимую зависимость.

Plugin.requires = { "acme.dsp" }

local dsp = Wex.import("acme.dsp", "^2.3.0")   -- nil + error if the installed acme.dsp is <2.3.0 or >=3.0.0
if dsp then
  local mags = dsp.fft(samples)
else
  Wex.toast("please install acme.dsp 2.x")
end

An aspect-oriented action pipeline for a plugin's own extensibility — the plugin, and any library it imports into its VM via Wex.import, can hook named actions the plugin fires. Four hook kinds run in priority order (higher first) when you fire(action, ctx): observe(fn) sees the context (no change); transform(fn) returns a new context, chained through each transform; intercept(fn) returns true to VETO, so fire returns { consumed = true } and stops; replace(fn) supplants the default and its return becomes fire's result (the highest-priority replace wins). fire(action, ctx) runs the pipeline and returns the transformed context, a replacement, or { consumed = true }; an action with no hooks returns ctx untouched. Each register returns an id for off(id); has(action) tests for any hook. A thrown hook is caught and logged, never breaking the pipeline. Same-VM and per-plugin — the sandbox-appropriate way a library extends its host plugin's behaviour without reaching into another plugin's VM.

Аспектно-ориентированный конвейер действий для расширяемости самого плагина — плагин и любая библиотека, импортированная в его VM через Wex.import, могут перехватывать именованные действия, которые плагин запускает. При fire(action, ctx) четыре типа хуков выполняются по приоритету (выше — раньше): observe(fn) видит контекст (без изменений); transform(fn) возвращает новый контекст, сцепляется через каждый transform; intercept(fn) возвращает true для ВЕТО, тогда fire возвращает { consumed = true } и останавливается; replace(fn) подменяет поведение по умолчанию, и его возврат становится результатом fire (побеждает replace с наибольшим приоритетом). fire(action, ctx) прогоняет конвейер и возвращает преобразованный контекст, замену или { consumed = true }; действие без хуков возвращает ctx без изменений. Каждая регистрация возвращает id для off(id); has(action) проверяет наличие. Исключение в хуке ловится и логируется, не ломая конвейер. В той же VM и per-plugin — подходящий для песочницы способ, которым библиотека расширяет поведение своего плагина, не залезая в чужую VM.

-- the plugin exposes an extensible "export" action; a library it imports can hook it too
Wex.hook.transform("export", 50, function(ctx)
  ctx.rows = dropHidden(ctx.rows); return ctx
end)
Wex.hook.intercept("export", 100, function(ctx)
  if #ctx.rows == 0 then Wex.toast("nothing to export"); return true end   -- veto
end)

local result = Wex.hook.fire("export", { rows = data, format = "csv" })
if not result.consumed then writeExport(result) end

Read-only access to assets/. Names may carry an asset: prefix. dataUri() feeds ui:image / ui:web; copyToFiles() clones a file into the writable Wex.files sandbox.

Доступ к assets/ только на чтение. Имена могут быть с префиксом asset:. dataUri() подходит для ui:image / ui:web; copyToFiles() копирует файл в записываемую песочницу Wex.files.

local cfg = Wex.assets.json("config.json")
for _, f in ipairs(Wex.assets.list("sounds")) do print(f) end

ui:image("asset:hero.png"), ui:icon("asset:btn.png"), ui:avatar("asset:me.jpg"), ui:web("asset:page.html"), Wex.audio.play("asset:boom.mp3"). No network permission needed — the file ships inside the package.

ui:image("asset:hero.png"), ui:icon("asset:btn.png"), ui:avatar("asset:me.jpg"), ui:web("asset:page.html"), Wex.audio.play("asset:boom.mp3"). Разрешение network не нужно — файл едет внутри пакета.

ui:image("asset:hero.png"):round("md")
ui:button("Play", function() Wex.audio.play("asset:boom.mp3") end)

Every icon slot takes a built-in name, an emoji, or an icon file from the package: ui:icon, ui:item{icon}, ui:tile, ui:stat{icon}, button:icon, ui:iconButton, ui:actions{icon}, ui:fab, input:icon / :endIcon, ui:dialog{icon}, ui:avatar and manifest.icon. Formats: png/jpg/webp/gif as-is; Android vector drawable XML and SVG (paths, circle/rect/ellipse/line/polyline/polygon, groups with transforms) are rasterized by WEX. Monochrome vectors are tinted to the theme like built-ins — download a Material icon from fonts.google.com as SVG or Android XML, drop it into assets/ and reference it.

Любой слот иконки принимает встроенное имя, эмодзи или файл из пакета: ui:icon, ui:item{icon}, ui:tile, ui:stat{icon}, button:icon, ui:iconButton, ui:actions{icon}, ui:fab, input:icon / :endIcon, ui:dialog{icon}, ui:avatar и manifest.icon. Форматы: png/jpg/webp/gif как есть; Android vector drawable XML и SVG (path, circle/rect/ellipse/line/polyline/polygon, группы с transform) WEX растеризует сам. Монохромные векторы окрашиваются в цвет темы как встроенные — скачай иконку Material с fonts.google.com в SVG или Android XML, положи в assets/ и укажи путь.

ui:item({ icon = "assets/wifi.svg", title = "Office AP" })
ui:button("Scan", scan):icon("assets/radar.xml")
ui:actions({ { label = "Sync", icon = "asset:sync.svg", onClick = sync } })

The IDE edits the whole package. The explorer button lists every file grouped by role (rename, duplicate, delete, replace an asset); open files become tabs. Typing offers completion from this very catalog with signatures and descriptions, inserting a template whose caret lands where you continue. Diagnostics run the real Lua compiler plus manifest, sandbox, require() and permission checks — findings appear in Problems, in the gutter and on the status bar, and tapping one jumps to the line. Run checks first and only then previews. Save installs the package; the workspace is the draft and survives closing the app.

Студия редактирует весь пакет. Кнопка проводника показывает все файлы, сгруппированные по роли (переименовать, дублировать, удалить, заменить ассет); открытые файлы становятся вкладками. При вводе работает автодополнение из этого же справочника — с сигнатурами и описанием, вставкой шаблона и курсором там, где продолжать. Диагностика запускает настоящий компилятор Lua плюс проверки манифеста, песочницы, require() и разрешений — находки видны в «Проблемах», в нумерации строк и в статус-баре, тап переходит к строке. «Запустить» сначала проверяет и только потом открывает превью. «Сохранить» устанавливает пакет; рабочая папка — черновик и переживает закрытие приложения.

Publishing a plugin with lib/ or assets/ creates the post and uploads the archive (up to 20 MB); the card shows files and size, Install downloads and unpacks. A plugin that is just main.lua is published the old way so older WEX builds can still install it. Opening a .wexp from a file manager or a chat installs it too.

Публикация плагина с lib/ или assets/ создаёт пост и загружает архив (до 20 МБ); карточка показывает файлы и размер, «Установить» скачивает и распаковывает. Плагин из одного main.lua публикуется по-старому, чтобы старые сборки WEX могли его поставить. Открытие .wexp из файлового менеджера или чата тоже устанавливает его.

Called once after the plugin has been replaced by a newer version, before the first Plugin.build. Installing an update rewrites only the package — main.lua, lib/ and assets/. Everything the plugin owns lives in a separate folder that install never touches: Wex.storage, Wex.secure, Wex.files and the Wex.db database all survive intact. That is exactly why the hook exists: when the new code expects a different shape, this is where the old data is migrated, before anything reads it.

Вызывается один раз после замены плагина новой версией, до первого Plugin.build. Установка обновления переписывает только пакет: main.lua, lib/ и assets/. Всё, что принадлежит плагину, лежит в отдельной папке, которую установка не трогает: Wex.storage, Wex.secure, Wex.files и база Wex.db остаются нетронутыми. Ради этого хук и нужен: если новый код ожидает другую структуру, именно здесь старые данные мигрируют, пока их никто не прочитал.

• oldVersionthe version that was installed before, as a string.версия, которая стояла раньше, строкой.
• newVersionthe version that has just been installed.версия, которая только что установлена.

function Plugin.onUpdate(oldVersion, newVersion)
  if oldVersion == "1.0" then
    -- 1.1 keeps hosts as a table instead of one string
    local single = Wex.storage.get("host")
    if single then
      Wex.storage.setJson("hosts", { single })
      Wex.storage.remove("host")
    end
  end
  Wex.log("migrated " .. oldVersion .. " -> " .. newVersion)
end

A link that installs a package in one tap. The app downloads it over https only, then runs the same flow a file tap uses: the manifest is read, the risk report is shown, and nothing is installed until the user confirms. Useful for an author distributing a .wexp from their own site; a plugin published on the forum is opened with wex://report/<id> instead, where the app already has the account that may install it.

Ссылка, которая ставит пакет в одно нажатие. Приложение скачивает его только по https, а дальше идёт тот же путь, что и при открытии файла: читается манифест, показывается отчёт о рисках, и без подтверждения пользователя ничего не устанавливается. Годится автору, который раздаёт .wexp со своего сайта; плагин с форума открывается через wex://report/<id>, где у приложения уже есть аккаунт, которому разрешена установка.

<a href="wex://install?url=https://example.com/my-plugin.wexp">Install in WEX</a>

Settings → Plugins → long-press → Share sends the actual file — .lua for a plain script, .wexp when the plugin has lib/ or assets/ — so anyone can re-import it.

Настройки → Плагины → долгое нажатие → Поделиться отправляет сам файл — .lua для одиночного скрипта, .wexp если у плагина есть lib/ или assets/ — его можно снова импортировать.

Long-press → Publish. The plugin name auto-fills the post title; you add a description. The script travels base64-encoded.

Долгое нажатие → Опубликовать. Имя плагина само становится заголовком; ты добавляешь описание. Скрипт едет в base64.

Forum → Plugins → tap a post → the page shows author, permissions, description (and files + size for a package) → Install. Same name already installed → Update / Reinstall / Separate copy.

Форум → Плагины → нажми на пост → страница с автором, разрешениями, описанием (для пакета — ещё файлы и размер) → Установить. То же имя уже стоит → Обновить / Переустановить / Отдельная копия.

In the install sheet, the author can delete their own post; a forum admin can delete any.

В окне установки автор может удалить свой пост; админ форума — любой.

Tap a .lua or .wexp in a file manager / chat / download and WEX offers to install it (a .lua that isn't a plugin opens in the editor).

Тапни .lua или .wexp в файловом менеджере / чате / загрузках — WEX предложит установить его (.lua, не являющийся плагином, откроется в редакторе).

Write the plugin in VS Code, Zed or Neovim and see every save on the phone. The editor starts a small HTTP server inside WEX (port 8765, Wi-Fi only) with a token that is new on every start; the dialog shows the full URL. Files pushed to it land in this editor's workspace, the open tab refreshes, and the preview re-runs in place — same screen, same rotation, Wex.state carried over. The server lives while the editor is open and stops when you install the plugin (the workspace folder is gone then).

Пишите плагин в VS Code, Zed или Neovim и видьте каждое сохранение на телефоне. Редактор поднимает маленький HTTP-сервер внутри WEX (порт 8765, только по Wi-Fi) с токеном, новым на каждый запуск; диалог показывает полный URL. Присланные файлы попадают в рабочую папку этого редактора, открытая вкладка обновляется, а предпросмотр перезапускается на месте: тот же экран, та же ориентация, Wex.state сохраняется. Сервер живёт, пока открыт редактор, и останавливается при установке плагина (рабочая папка удаляется).

# on the computer, once (Node 18+, no npm install):
node wex-dev.mjs "http://192.168.1.20:8765/?token=abcd2345" ./my-plugin

# or push one file on save (VS Code "Run on Save", a Makefile, anything):
curl -T main.lua -H "X-Wex-Token: abcd2345" http://192.168.1.20:8765/files/main.lua

The dialog exports wex-dev.mjs, a dependency-free Node 18+ script with four jobs. init <name> --permissions a,b scaffolds a folder: manifest.json, main.lua with a working Plugin.build for the permissions you asked for, lib/util.lua, assets/icon.svg and a .luarc.json that points the Lua Language Server at the types. defs <url> downloads wex-api.def.lua from the phone, so the completion always matches the build you are testing against. With a URL and a folder it syncs once, watches, pushes each changed file and tails the plugin log. The HTTP API behind it is plain: every request carries X-Wex-Token (or ?token=), paths are relative to the workspace, bodies are raw file contents, and /log long-polls up to 25 s. Dotfiles, node_modules and the definitions file are never pushed.

Диалог экспортирует wex-dev.mjs — скрипт для Node 18+ без зависимостей, у него четыре задачи. init <имя> --permissions a,b разворачивает каркас: manifest.json, main.lua с рабочим Plugin.build под запрошенные разрешения, lib/util.lua, assets/icon.svg и .luarc.json, который указывает Lua Language Server на файл типов. defs <url> скачивает wex-api.def.lua с телефона, поэтому автодополнение всегда совпадает со сборкой, на которой вы тестируете. С URL и папкой он один раз синхронизирует, следит за изменениями, отправляет каждый изменённый файл и выводит лог плагина. HTTP API под ним простой: каждый запрос несёт X-Wex-Token (или ?token=), пути относительны рабочей папки, тело — содержимое файла, /log держит long-poll до 25 с. Dot-файлы, node_modules и файл типов не отправляются.

# a new plugin, types included, in one command
node wex-dev.mjs init my-sensor-tool --permissions "bluetooth,files" --url "http://192.168.1.20:8765/?token=abcd2345"

# then edit in VS Code and let the phone follow along
node wex-dev.mjs "http://192.168.1.20:8765/?token=abcd2345" ./my-sensor-tool

Bold heading.

Жирный заголовок.

• sthe heading text.текст заголовка.

returnsвозвращаетa style handle (see UI · styling).хендл стиля (см. UI · стилизация).

ui:title("Settings")

Body text. html() renders basic tags (b, i, a, br, font color…).

Обычный текст. html() рендерит базовые теги (b, i, a, br, font color…).

• splain text, or HTML for html().простой текст, или HTML для html().

returnsвозвращаетa handle: h:get() reads, h:set(v) replaces the text.хендл: h:get() читает, h:set(v) заменяет текст.

local out = ui:text("")
out:set("done")

Secondary heading (16sp bold) and small muted meta text (11sp) — semantic sizes from the type scale, so screens stay visually consistent without guessing sizes.

Второстепенный заголовок (16sp, жирный) и мелкий приглушённый текст (11sp) — семантические размеры для единообразия экранов без подбора размеров на глаз.

• sthe text.текст.

returnsвозвращаетa handle: h:get() reads, h:set(v) replaces the text.хендл: h:get() читает, h:set(v) заменяет текст.

ui:subtitle("Connection")
ui:caption("updated 2s ago")

A settings-style row: muted label on the left, bold value on the right. Ideal for status/info screens.

Строка вида «настройка»: приглушённая подпись слева, жирное значение справа. Для экранов статуса/инфо.

• labelleft-aligned caption.подпись слева.
• valueright-aligned, bold.значение справа, жирным.

returnsвозвращаетa handle on the value: h:get()/h:set(v) to update it live.хендл значения: h:get()/h:set(v) для живого обновления.

local rtt = ui:kv("Ping", "…")
Wex.interval(1000, function() rtt:set(measure() .. " ms") end)

Small status pill — tone tints both text and background so it reads clearly in light and dark.

Маленькая плашка статуса — tone задаёт цвет текста и мягкий фон, читаемо в светлой и тёмной теме.

• textshort label, e.g. "online".короткая подпись, напр. "online".
• tone"success" / "warning" / "danger" / "info" / "neutral" (default)."success" / "warning" / "danger" / "info" / "neutral" (по умолчанию).

ui:row(function(c)
  c:text("Status"):grow()
  c:badge("online", "success")
end)

Centered placeholder for an empty list or a not-yet-loaded state.

Центрированная заглушка для пустого списка или состояния до загрузки.

• iconan emoji shown large on top.эмодзи крупно сверху.
• title / subtitlebold heading and muted detail line.жирный заголовок и приглушённая строка.

ui:empty("info", "Nothing yet", "Pull down to refresh")

Filled button.

Заполненная кнопка.

• labelbutton caption.надпись на кнопке.
• fncalled on tap, no arguments.вызов по тапу, без аргументов.

ui:button("Run", function()
  ui:toast("tapped")
end)

Outlined button that opens a URL in the browser.

Кнопка-контур, открывает URL в браузере.

• labelbutton caption.надпись.
• urlthe address to open.адрес для открытия.

ui:link("Docs", "https://lua.org")

Single-line text field. :set(s) triggers :onChange like typing does.

Однострочное поле ввода. :set(s) вызывает :onChange так же, как ввод с клавиатуры.

• hintplaceholder shown when empty.подсказка, когда пусто.
• initinitial text (optional).начальный текст (необязательно).

returnsвозвращаетa handle: h:get() → current text, h:set(v) writes it.хендл: h:get() → текущий текст, h:set(v) записывает.

local url = ui:input("URL", "https://")
-- later: url:get()

Boolean toggle / checkbox. :set(b) and :toggle() call fn as well; nothing is called while the widget is created.

Булев переключатель / чекбокс. :set(b) и :toggle() тоже вызывают fn; при создании виджета ничего не вызывается.

• labeltext next to the control.текст рядом с контролом.
• oninitial state, true/false.начальное состояние, true/false.
• fn(checked)called with the new boolean.вызов с новым булевым значением.

ui:switch("Dark", true, function(on)
  ui:toast(tostring(on))
end)

Value slider. :set(v) calls fn when the value changes; nothing is called while the widget is created.

Слайдер значения. :set(v) вызывает fn при смене значения; при создании виджета ничего не вызывается.

• from / torange bounds.границы диапазона.
• stepincrement; 0 = smooth.шаг; 0 = плавно.
• initstarting value.стартовое значение.
• fn(value)called as it moves.вызов при движении.

ui:slider("Vol", 0, 100, 5, 30, function(v)
  print(v)
end)

Radio group from a list of strings.

Радио-группа из списка строк.

• {..}array of option labels.массив подписей вариантов.
• fn(index, value)on select; index is 1-based.при выборе; index с 1.
• initialoptional — 1-based index to preselect; when given, fn(initial, label) runs inside the constructor.необязательно — индекс с 1 для предвыбора; если передан, fn(initial, label) выполняется внутри конструктора.

ui:radio({"A", "B"}, function(i, v)
  ui:toast(v)
end)

Number stepper with − / + buttons.

Числовой степпер с кнопками − / +.

• min / maxbounds.границы.
• initstarting number.стартовое число.
• fn(value)on each change.при каждом изменении.

ui:stepper("Qty", 1, 9, 1, function(n) end)

Single choice from a list. chips = inline pills; dropdown = exposed menu.

Одиночный выбор из списка. chips = плитки в ряд; dropdown = выпадающее меню.

• hintdropdown placeholder (dropdown only).подсказка выпадашки (только dropdown).
• {..}array of option labels.массив вариантов.
• fn(index, value)on selection.при выборе.
• initialoptional — preselect: chips take a 1-based index, dropdown an index or the label string. Preselecting this way does not call fn.необязательно — предвыбор: chips принимают индекс с 1, dropdown — индекс или строку-подпись. Такой предвыбор fn не вызывает.

ui:dropdown("Method", {"GET", "POST"}, function(i, v) end)

Built-in vector icon.

Встроенная векторная иконка.

• namesearch / delete / key / qr / mail / wifi / copy / refresh / …search / delete / key / qr / mail / wifi / copy / refresh / …
• sizedp (default 24).dp (по умолчанию 24).

ui:icon("wifi", 32)

Shows an image (downsampled). http(s) needs "network"; a data:…;base64 URI is decoded locally with no permission.

Показывает картинку (с уменьшением). http(s) требует "network"; data:…;base64 декодируется локально без разрешения.

• urlhttp(s) address, or a data:image/…;base64,… URI.адрес http(s), или data:image/…;base64,… URI.

ui:image("data:image/png;base64,iVBORw0K…")

Divider line; vertical gap; brief message; remove all widgets on the screen.

Линия-разделитель; вертикальный отступ; короткое сообщение; очистить экран.

• dpspacer height — a dp number, or a token ("xs"/"sm"/"md"/"lg"/"xl"/"xxl").высота отступа — число dp или токен ("xs"/"sm"/"md"/"lg"/"xl"/"xxl").
• sthe toast text.текст всплывашки.

ui:spacer("md")
ui:toast("saved")

A two-thumb slider for a range; fn(a, b) fires as either thumb moves. h:get() → { a, b }, h:set(a, b).

Ползунок с двумя бегунками для диапазона; fn(a, b) вызывается при движении любого. h:get() → { a, b }, h:set(a, b).

Nested containers — card box, horizontal row, vertical column.

Вложенные контейнеры — карточка, горизонтальная строка, вертикальная колонка.

• fn(c)builder; `c` is a fresh ui bound to the container.билдер; `c` — новый ui, привязанный к контейнеру.
• gapoptional — spacing between children: a dp number or a token ("xs"/"sm"/"md"/"lg"/"xl"/"xxl"). Replaces per-widget default spacing with one uniform value; omit to keep old behavior.необязательно — отступ между детьми: число dp или токен ("xs"/"sm"/"md"/"lg"/"xl"/"xxl"). Заменяет отступы по умолчанию одним значением; не указывай — прежнее поведение сохранится.

ui:row(function(c)
  c:button("A", f):grow()
  c:button("B", f):grow()
end, "md")

A whole screen's chrome in one call: a large title that collapses into the toolbar as the content scrolls (set large=false for a plain toolbar title), an optional subtitle, a FAB, toolbar actions, pull-to-refresh, and the content. fab is { icon, label, onClick }; actions is the same list as ui:actions; refresh(done) is called on a pull and must call done() when it finishes; build(c) fills the content with a normal ui. It decorates the current screen (it is not itself a pushed screen).

Весь chrome экрана одним вызовом: крупный заголовок, схлопывающийся в тулбар по мере прокрутки (large=false — обычный заголовок в тулбаре), необязательный подзаголовок, FAB, действия тулбара, pull-to-refresh и контент. fab — { icon, label, onClick }; actions — тот же список, что у ui:actions; refresh(done) вызывается на потягивании и обязан вызвать done() по завершении; build(c) наполняет контент обычным ui. Оформляет текущий экран (сам он не является push-экраном).

function Plugin.build(ui)
  ui:scaffold({
    title = "Inbox", subtitle = "3 unread",
    fab = { icon = "edit", label = "Compose", onClick = compose },
    actions = { { icon = "refresh", onClick = reload } },
    refresh = function(done) fetch(function() done() end) end,
    build = function(c)
      c:list({ count = #items, render = function(row, i) row:text(items[i]) end })
    end,
  })
end

A list. Omit height and it grows to fit all rows (the whole page scrolls). Give a dp height for a fixed scrollable window that virtualizes — only visible rows are built.

Список. Без height растёт под все строки (скроллится вся страница). Число dp — фиксированное окно со скроллом и виртуализацией (строятся только видимые строки).

• countnumber of items.число элементов.
• heightoptional: a dp number for a fixed scroll window, "match" to fill, or omit to grow to fit.необязательно: число dp для фикс. окна скролла, "match" — заполнить, или опусти, чтобы растянуть под содержимое.
• render = fn(row, i)builds item i (1-based) on the given `row` ui.строит элемент i (с 1) на данном `row` ui.

ui:list({ count = #items,
  render = function(row, i) row:text(items[i]) end })

Read-only, selectable, syntax-highlighted viewer.

Только чтение, выделяемый, с подсветкой синтаксиса.

• textthe content to show.содержимое для показа.
• lang"json" or "lua"."json" или "lua".

ui:code(body, "json")

Bottom sheet.

Нижняя шторка.

• titlesheet heading.заголовок шторки.
• fn(sheet)builds it; call sheet:close() to dismiss.строит её; sheet:close() закрывает.

ui:sheet("More", function(s)
  s:button("Close", function() s:close() end)
end)

Stack navigation — push opens a new screen; pop / system Back returns.

Стековая навигация — push открывает новый экран; pop / системный Back возвращает.

• titlenew screen's toolbar title.заголовок тулбара нового экрана.
• fn(screen)builds the pushed screen.строит открытый экран.

ui:push("Detail", function(s)
  s:button("Back", function() s:pop() end)
end)

Linear / circular progress indicator.

Линейный / круговой индикатор прогресса.

returnsвозвращаетa handle: h:show(), h:hide(); linear also h:set(pct) 0–100.хендл: h:show(), h:hide(); у линейного ещё h:set(pct) 0–100.

local p = ui:progress()
p:show(); p:set(40)

An expressive wavy progress bar. Pass a number 0–100, or { value=, max=, color= }; omit the argument for an indeterminate bar. Drawn by WEX, so it looks the same on every device.

Экспрессивный «волнистый» индикатор прогресса. Передай число 0–100 или { value=, max=, color= }; без аргумента — бесконечный. Рисуется самим WEX, поэтому выглядит одинаково на любом устройстве.

returnsвозвращаетa handle: h:set(value, max?), h:indeterminate(), h:color(c), h:show(), h:hide().хендл: h:set(value, max?), h:indeterminate(), h:color(c), h:show(), h:hide().

local w = ui:wavyProgress({ value = 40 })
w:set(70, 100)

A declarative container: the builder re-runs whenever any watched Wex.state key changes, so you write `if Wex.state.ready then … else … end` instead of tracking handles and calling :show()/:hide() by hand. Pass no keys to react to every state change. h:refresh() forces a rebuild, h:stop() detaches. Watchers drop automatically when the view leaves the screen.

Декларативный контейнер: билдер перезапускается при изменении любого отслеживаемого ключа Wex.state, поэтому пишешь `if Wex.state.ready then … else … end` вместо ручного хранения хендлов и вызовов :show()/:hide(). Без ключей реагирует на любое изменение состояния. h:refresh() пересобрать принудительно, h:stop() отписаться. Наблюдатели снимаются сами, когда вью уходит с экрана.

Zero-lag reconciliation for reactive UI. A ui:view rebuilds at most ONCE per display frame no matter how many of its watched Wex.state keys change in between. When a firehose — a multi-megabaud UART, a GNSS / sensor stream, a driver + Wex.dsp.graph pipeline, or a db:live / Wex.bus.state query — updates state many times inside one ~8–16 ms frame, the view coalesces them (via the display Choreographer) into a single rebuild on the next vsync, which sees the latest state: no wasted layout passes, no mid-frame flicker, smooth at 60/120 Hz under load. The first paint is immediate; w:refresh() still forces an immediate rebuild; and writing a key its current value never triggers a rebuild. Pair ui:view with Wex.bus.state or db:live to drive a live dashboard that stays fluid while ingesting a continuous stream.

Zero-lag reconciliation для реактивного UI. ui:view перестраивается не чаще ОДНОГО раза за кадр дисплея, сколько бы его watched-ключей Wex.state ни изменилось между кадрами. Когда firehose — UART на мегабоды, поток GNSS / сенсоров, конвейер драйвер + Wex.dsp.graph или запрос db:live / Wex.bus.state — обновляет состояние много раз за один ~8–16 мс кадр, view коалесцирует их (через дисплейный Choreographer) в одну перестройку на следующем vsync, видящую последнее состояние: без лишних layout-проходов, без дёрганья в середине кадра, плавно на 60/120 Гц под нагрузкой. Первая отрисовка немедленная; w:refresh() по-прежнему форсирует немедленную перестройку; запись ключу его же значения перестройку не вызывает. Сочетай ui:view с Wex.bus.state или db:live для живого дашборда, остающегося плавным при непрерывном потоке.

local v = ui:view({ "snr", "spectrum" }, function(ui)
  ui:text(("SNR %.1f dB"):format(Wex.state.snr or 0))
  ui:spectrum(Wex.state.spectrum)
end)

-- a driver/DSP firehose writes state many times per frame; ui:view rebuilds once per vsync
dev.rx(function(frame)
  local r = graph:process(frame)
  Wex.state.snr = r.snr
  Wex.state.spectrum = r.mag        -- coalesced → a single rebuild on the next frame
end)

Skeleton instantly, async work off the UI thread, then the real content. start(done) kicks off the op (Wex.http, Wex.worker():next, a timer…) and calls done(result) when finished; render(ui, result) then fills the container on the main thread. One convention: result is a value you check with Wex.ok in render — normalise a Wex.worker :catch to done({ ok = false, error = e }). Heavy work never sits in Plugin.build, so the 4-second build watchdog is never in play. opts is the ui:skeleton shape ({ lines, height, gap }); skeleton = false shows nothing. Leaving the screen invalidates in-flight work, so ui:load is safe to nest; the ui passed to render is a full nested ui — you can call ui:load / ui:view / containers on it again. h:reload() runs start again.

Скелет мгновенно, async-работа вне UI-потока, затем настоящий контент. start(done) запускает операцию (Wex.http, Wex.worker():next, таймер…) и зовёт done(result) по завершении; render(ui, result) наполняет контейнер на главном потоке. Одна конвенция: result проверяется через Wex.ok в render — worker :catch нормализуй в done({ ok = false, error = e }). Тяжёлое не сидит в Plugin.build, поэтому сторож 4 сек не в игре. opts — форма ui:skeleton ({ lines, height, gap }); skeleton = false скрывает плейсхолдер. Уход с экрана инвалидирует незавершённую работу, поэтому ui:load безопасно вкладывать; переданный в render ui — полноценный вложенный ui, на нём снова доступны ui:load / ui:view / контейнеры. h:reload() запускает start заново.

ui:load(function(done)
  Wex.http(url, function(res) done(res) end)
end, function(ui, res)
  if not Wex.ok(res) then ui:text("Ошибка"):color("error") return end
  ui:title(res.body)
end, { lines = 3 })

A Z-stack: each layer is its own builder drawn over the previous one, so an interactive widget can sit on top of an image, chart or canvas instead of the strict vertical/horizontal flow of ui:column / ui:row. align places a layer ("center", "bottom_end", …), offsetX/offsetY nudge it in dp, fill = true stretches it. A bare function works as a layer too. h:layer(i) returns that layer's handle.

Z-стек: каждый слой — свой билдер поверх предыдущего, поэтому интерактивный виджет можно положить на картинку, график или canvas, а не выстраивать строго по вертикали/горизонтали как в ui:column / ui:row. align задаёт место слоя ("center", "bottom_end", …), offsetX/offsetY смещают в dp, fill = true растягивает. Голая функция тоже работает как слой. h:layer(i) вернёт хендл слоя.

A navigation bar whose panes keep their own state: each pane is built once on first visit and then only shown or hidden, so switching tabs preserves scroll position, typed input and anything the pane created — the part ui:tabs cannot do, because it rebuilds. items are { icon, label, build = fn(pane) }. position "bottom" (default) or "top". h:select(i), h:current(), h:pane(i). The initial pane's build and onChange(initial) run inside the constructor; h:select(i) runs onChange only when the pane actually changes.

Панель навигации, вкладки которой сохраняют своё состояние: каждая панель строится один раз при первом открытии, дальше только показывается и прячется — поэтому при переключении сохраняются прокрутка, введённый текст и всё, что панель создала. Это то, чего не умеет ui:tabs: он пересобирает. items — { icon, label, build = fn(pane) }. position "bottom" (по умолчанию) или "top". h:select(i), h:current(), h:pane(i). build начальной панели и onChange(initial) выполняются внутри конструктора; h:select(i) вызывает onChange только при реальной смене панели.

Setters chain — each returns the handle, so you keep calling on the result.

Сеттеры чейнятся — каждый возвращает хендл, вызывай дальше по результату.

ui:text("Hi"):align("center"):color("#38BDF8"):textSize(16)

Widget dimensions.

Размеры виджета.

• v / w / ha number in dp, or "match" / "wrap".число в dp, либо "match" / "wrap".

ui:button("Wide", f):width("match"):height(56)

align = position within the parent; gravity = inner content alignment.

align = позиция в родителе; gravity = выравнивание содержимого.

• gstart / center / end / top / bottom / center_h / center_v.start / center / end / top / bottom / center_h / center_v.

ui:text("R"):align("end")

Outer margins / inner padding — one value for all sides, or four. Each value is a dp number or a token ("xs"=4 "sm"=8 "md"=12 "lg"=16 "xl"=24 "xxl"=32).

Внешние / внутренние отступы — одно значение на все стороны или четыре. Каждое значение — число dp или токен ("xs"=4 "sm"=8 "md"=12 "lg"=16 "xl"=24 "xxl"=32).

ui:card(f):margin("sm", "md", "sm", "md"):padding("lg")

weight = LinearLayout weight (use inside ui:row/column, with width 0). color / textSize apply to text widgets.

weight = вес в LinearLayout (внутри ui:row/column, ширина 0). color / textSize — для текстовых виджетов.

c:button("Half", f):width(0):weight(1)
ui:text("Red"):color("#F00"):textSize(18)

Size constraints in dp. max* apply to text and images.

Ограничения размера в dp. max* — для текста и картинок.

ui:text(long):maxLines(2):maxWidth(200)

Shorthand for width 0 + weight 1 — fills the remaining space in a ui:row.

Сокращение для ширины 0 + веса 1 — занимает остаток места в ui:row.

ui:row(function(c)
  c:button("A", f):grow()
  c:button("B", f):grow()
end)

Set one margin side without touching the others. dp or a spacing token.

Задать одну сторону внешнего отступа, не трогая остальные. dp или токен отступа.

ui:card(f):marginTop("lg"):marginBottom("sm")

Horizontal / vertical inner padding, keeping the other axis. dp or a spacing token.

Горизонтальный / вертикальный внутренний отступ, сохраняя другую ось. dp или токен отступа.

ui:button("Wide", f):paddingH("xl"):paddingV("sm")

Center the widget within its parent (same as :align("center")).

Центрировать виджет в родителе (как :align("center")).

ui:title("Hi"):center()

Background color — on a card sets the card color, on a button the tint, else the view background.

Цвет фона — у карточки цвет карточки, у кнопки тинт, иначе фон вью.

ui:card(f):bg("#111827")

Corner radius (dp or a token: "sm"=8 "md"=16 "lg"=24 "full"=pill) and shadow — for cards and buttons.

Скругление (dp или токен: "sm"=8 "md"=16 "lg"=24 "full"=таблетка) и тень — для карточек и кнопок.

ui:card(f):radius("lg"):elevation(4)

Opacity and rotation of any widget.

Прозрачность и поворот любого виджета.

ui:icon("star", 40):alpha(0.5):rotation(45)

Text styling — bold / italic / monospace font / line clamp.

Стиль текста — жирный / курсив / моноширинный / ограничение строк.

ui:text("Code"):mono():bold()

Toggle visibility (works on any widget) and interactivity.

Переключить видимость (у любого виджета) и активность.

local b = ui:button("Go", f)
b:enabled(false)

Attach a tap handler to any widget — e.g. make a card or text tappable.

Повесить обработчик тапа на любой виджет — например, сделать карточку или текст кликабельными.

ui:card(function(c) c:text("tap me") end)
  :onClick(function() ui:toast("tapped") end)

The type scale on any text handle: one size + weight vocabulary instead of raw textSize, so headings and body line up across every plugin. ui:type("title") also returns the size in sp if you need the number.

Типографическая шкала на любом текстовом хендле: единый набор размер+начертание вместо голого textSize, чтобы заголовки и текст совпадали во всех плагинах. ui:type("title") также вернёт размер в sp, если нужно число.

Set the typeface: a built-in family, or a custom font shipped in your plugin’s assets/ (.ttf/.otf), loaded once and cached. Preload/validate with ui:font("assets/…") (returns the path or nil).

Задать шрифт: встроенное семейство или свой шрифт из assets/ плагина (.ttf/.otf), загружается один раз и кэшируется. Предзагрузить/проверить через ui:font("assets/…") (вернёт путь или nil).

A background image from the plugin’s assets on any view (and cards). fit = "stretch" | "contain" | "tile"; radius as a token or dp; overlay = a colour drawn over the image so text stays legible. Pairs well with ui:hero and full-bleed cards.

Фоновая картинка из assets плагина на любой вью (и карточках). fit = "stretch" | "contain" | "tile"; radius токеном или в dp; overlay = цвет поверх картинки, чтобы текст оставался читаемым. Хорошо сочетается с ui:hero и карточками во весь экран.

Full custom dialog built from a table of fields.

Полный кастомный диалог из таблицы полей.

• title / messageheader and body text.заголовок и текст.
• content = fn(d)builds custom widgets via a nested ui `d`.строит виджеты вложенным ui `d`.
• positive / negative / neutralbutton labels (default OK).подписи кнопок (по умолчанию OK).
• onPositive / onNegative / onNeutralper-button callbacks (optional).колбэки кнопок (необязательно).

local f
ui:dialog{ title = "Name",
  content = function(d) f = d:input("You", "") end,
  positive = "OK", onPositive = function() ui:toast(f:get()) end }

Yes / No dialog.

Диалог Да / Нет.

• messagethe question.вопрос.
• fnruns only when the user confirms.вызов только при подтверждении.

ui:confirm("Delete?", function() remove() end)

Single-input dialog.

Диалог с одним полем.

• title / hintheader and field placeholder.заголовок и подсказка поля.
• fn(text)receives the entered text on OK.получает введённый текст по OK.

ui:prompt("Rename", "new name", function(t) end)

HTTP request. Runs off the main thread; fn is posted back to the main thread.

HTTP-запрос. Выполняется вне главного потока; fn возвращается в главный поток.

• urla string for a simple GET.строка для простого GET.
• opts{ url, method, headers = {k=v}, body }.{ url, method, headers = {k=v}, body }.
• fn(res)res = { ok, status, body, error }.res = { ok, status, body, error }.

Wex.http({ url = u, method = "POST", body = j },
  function(res) if res.ok then print(res.body) end end)

Nil-safe result guards. ok(res) is true only when res is a table whose .ok is set — safe even if the callback got nil. err(res) returns its .error string, or nil. Put them at the top of every callback so a failed result is never read.

Nil-безопасные проверки результата. ok(res) истинно, только если res — таблица с истинным .ok (безопасно даже при nil). err(res) возвращает .error (строку) или nil. Ставьте их в начале каждого колбэка, чтобы упавший результат не читался дальше.

Wex.http("https://api.ipify.org", function(res)
  if not Wex.ok(res) then Wex.log(Wex.err(res)) return end
  out:set(res.body)
end)

Opens a websocket connection.

Открывает websocket-соединение.

• urlws:// or wss:// address.адрес ws:// или wss://.
• handlers{ onOpen, onMessage(text), onClose(reason), onError(msg) }.{ onOpen, onMessage(text), onClose(reason), onError(msg) }.

returnsвозвращаетws with ws:send(text) and ws:close().ws с ws:send(text) и ws:close().

local ws = Wex.websocket(u, { onMessage = function(t) print(t) end })
ws:send("hi")

Downloads a binary into the plugin's file sandbox.

Скачивает бинарь в файловую песочницу плагина.

• urlsource address.адрес источника.
• filenamesandbox file name to write.имя файла в песочнице.
• fn(ok)boolean success.булев успех.

Wex.download(u, "pic.jpg", function(ok) end)

multipart/form-data POST.

POST multipart/form-data.

• opts.fields{ k = v } form fields.{ k = v } поля формы.
• opts.files{{ field, path, filename }} — path is a sandbox file.{{ field, path, filename }} — path из песочницы.
• fn(res)res = { ok, status, body }.res = { ok, status, body }.

Wex.upload(u, { files = {{ field="f", path="pic.jpg" }} },
  function(res) end)

Per-plugin key/value strings that persist across restarts.

Пер-плагинные строки ключ/значение, переживают перезапуск.

• get(k)→ string or nil.→ строка или nil.
• set(k, v)store a string.сохранить строку.
• remove(k) keys()delete one; list all key names.удалить один; список всех ключей.

Wex.storage.set("count", "1")
local c = Wex.storage.get("count")

Like storage but AES-256-GCM encrypted with an OS Keystore key — for secrets.

Как storage, но шифруется AES-256-GCM ключом из Keystore — для секретов.

• get(k) set(k, v) remove(k)same shape as storage.как у storage.

Wex.secure.set("api_key", key)

Text files inside the plugin's private folder. Names are basenames (no path escape).

Текстовые файлы в приватной папке плагина. Имена без путей (без выхода).

• read(name)→ text or nil.→ текст или nil.
• write(name, text)create / overwrite.создать / перезаписать.
• delete(name) exists(name) list()remove; check; list names.удалить; проверить; список имён.

Wex.files.write("log.txt", "hi")

SQLite database in the sandbox.

База SQLite в песочнице.

• db:exec(sql, {params})run a write / DDL statement.запись / DDL.
• db:query(sql, {params})→ array of row tables.→ массив строк-таблиц.
• db:close()release the handle.освободить хендл.

local db = Wex.db.open("data.db")
db:exec("CREATE TABLE IF NOT EXISTS t(x)")
local rows = db:query("SELECT * FROM t")

System file dialogs for the user's real files.

Системные файловые диалоги для настоящих файлов пользователя.

• pick fn(res)res = { name, content } or { error }.res = { name, content } или { error }.
• save name / contentsuggested name and text to write.предлагаемое имя и текст для записи.
• save fn(ok)boolean success.булев успех.

Wex.pickFile(function(res)
  if res.content then ui:text(res.content) end
end)

WEX file picker — browse the on-device /WEX folder (bases, downloads, …) with no SAF dialog.

Файлпикер WEX — обзор папки /WEX на устройстве (базы, загрузки, …) без SAF-диалога.

• fn(res)res = { name, path, size, content } or { error }. content only for files under 2 MB.res = { name, path, size, content } или { error }. content только для файлов до 2 МБ.

Wex.pickWexFile(function(res)
  if res.content then ui:text(res.content) end
end)

Durable folder access through the system tree picker (Storage Access Framework). pick(fn) asks the user to grant a folder once; the grant is persisted, so saved() lists the folders THIS plugin was granted as { uri, name } and open(uri) reopens one on a later run without asking again (a plugin never sees a folder another plugin or the app granted). A folder handle carries uri and name and does async I/O: folder:list(fn) → { name, isDir, size, mime, uri }; folder:readText(name, fn); folder:writeText(name, text, fn(ok)) (creates or overwrites); folder:delete(name, fn(ok)). Files are addressed by their direct-child name — a flat view of the chosen folder. Foreground plugins only. Needs Plugin.permissions = {"files"}.

Постоянный доступ к папке через системный выбор дерева (Storage Access Framework). pick(fn) один раз просит пользователя выдать папку; доступ сохраняется, поэтому saved() перечисляет папки, выданные ИМЕННО этому плагину, как { uri, name }, а open(uri) открывает её при следующем запуске без повторного запроса (папку, выданную другим плагином или самим приложением, плагин не видит). Хендл папки хранит uri и name и делает async-I/O: folder:list(fn) → { name, isDir, size, mime, uri }; folder:readText(name, fn); folder:writeText(name, text, fn(ok)) (создаёт или перезаписывает); folder:delete(name, fn(ok)). Файлы адресуются по имени прямого потомка — плоский вид выбранной папки. Только для плагинов на переднем плане. Нужно Plugin.permissions = {"files"}.

Plugin.permissions = { "files" }

Wex.folder.pick(function(dir)
  if not dir then return end          -- user cancelled
  dir:writeText("note.txt", "hello", function(ok)
    dir:list(function(items)
      for _, f in ipairs(items) do Wex.log(f.name) end
    end)
  end)
end)

The binary counterparts of readText / writeText on a Wex.folder handle. read hands the file's bytes to fn as a base64 string (nil when the file is missing, unreadable, or larger than 24 MB); write creates-or-overwrites the file from a base64 string and reports ok. base64 is the same convention as Wex.pickBinary and Wex.saveBase64 — so a photo from Wex.camera.capture (via Wex.image … :toBase64()) or any binary can be dropped straight into the granted folder. Both run off the main thread.

Бинарные аналоги readText / writeText у хендла Wex.folder. read отдаёт байты файла в fn как строку base64 (nil, если файла нет, он нечитаем или больше 24 МБ); write создаёт или перезаписывает файл из строки base64 и сообщает ok. base64 — та же схема, что у Wex.pickBinary и Wex.saveBase64, поэтому фото из Wex.camera.capture (через Wex.image … :toBase64()) или любой бинарник можно положить прямо в выданную папку. Обе операции работают вне главного потока.

Wex.folder.pick(function(dir)
  if not dir then return end
  dir:read("photo.jpg", function(b64)
    if b64 then
      dir:write("copy.jpg", b64, function(ok) Wex.toast(ok and "copied" or "failed") end)
    end
  end)
end)

Lua table ↔ JSON string. Arrays use 1-based integer keys.

Lua-таблица ↔ JSON-строка. Массивы — целочисленные ключи с 1.

• encode(t)table → JSON string.таблица → JSON-строка.
• decode(s)JSON string → table (nil on error).JSON-строка → таблица (nil при ошибке).

local t = Wex.json.decode(res.body)
print(t.name)

Base64 of a UTF-8 string.

Base64 от UTF-8-строки.

returnsвозвращаетencode → string; decode → string or nil on invalid input.encode → строка; decode → строка или nil при неверном вводе.

local b = Wex.base64.encode("hi")

Hex digest of the input string.

Hex-дайджест входной строки.

• sthe data to hash.данные для хеша.

local h = Wex.hash.sha256("password")

HMAC hex signature — for API auth / webhooks.

HMAC-подпись (hex) — для авторизации API / вебхуков.

• msgthe data to sign.данные для подписи.
• keythe secret.секрет.

local sig = Wex.crypto.hmacSha256(payload, secret)

AES-256-GCM with a passphrase (PBKDF2).

AES-256-GCM с парольной фразой (PBKDF2).

• text / blobplaintext to encrypt / base64 blob to decrypt.текст для шифра / base64-blob для расшифровки.
• passthe passphrase.парольная фраза.

returnsвозвращаетencrypt → base64 blob; decrypt → text or nil.encrypt → base64-blob; decrypt → текст или nil.

local b = Wex.crypto.aesEncrypt("secret", pw)

Current time.

Текущее время.

returnsвозвращаетepoch milliseconds (number).миллисекунды эпохи (число).

local t = Wex.now()

Compiles & runs Lua in a fresh sandbox (bounded — a runaway loop is killed).

Компилирует и выполняет Lua в свежей песочнице (ограничено — зависший цикл прерывается).

• luaStringsource to run.исходник для запуска.

returnsвозвращаетits first result, or nil on error.первый результат, или nil при ошибке.

local r = Wex.eval("return 2 + 2")

A random UUID v4 string.

Случайный UUID v4 (строка).

local id = Wex.uuid()

Date/time helpers — os.date is unavailable in the sandbox.

Хелперы даты/времени — os.date в песочнице недоступен.

• now()epoch milliseconds.миллисекунды эпохи.
• format(ms, pattern)→ string, e.g. "yyyy-MM-dd HH:mm".→ строка, напр. "yyyy-MM-dd HH:mm".
• parse(str, pattern)→ ms, or nil if it doesn't match.→ ms, или nil если не совпало.
• iso(ms) startOfDay(ms)ISO-8601 string; midnight of that day.строка ISO-8601; полночь того дня.

Wex.time.format(Wex.time.now(), "HH:mm:ss")

32-bit bitwise operations for parsing binary packets (vanilla Lua 5.2 has no bitwise operators). LuaJIT-compatible core plus field helpers: Wex.bit.extract(x, from, width) pulls an unsigned bitfield, Wex.bit.test(x, n) checks one bit, Wex.bit.replace(x, v, from, width) writes a field. Example: local hi = Wex.bit.extract(header, 4, 4).

32-битные битовые операции для разбора бинарных пакетов (в ванильном Lua 5.2 нет битовых операторов). Ядро в стиле LuaJIT плюс помощники для полей: Wex.bit.extract(x, from, width) достаёт беззнаковое битовое поле, Wex.bit.test(x, n) проверяет один бит, Wex.bit.replace(x, v, from, width) пишет поле. Пример: local hi = Wex.bit.extract(header, 4, 4).

Signal processing for the mic and radio streams. Wex.dsp.fft(samples) → magnitude spectrum (N/2 bins); dominantFreq(samples, rate) → the strongest frequency in Hz; rms/peak level; hann(n) window. Pure math, runs headless too.

Обработка сигналов для микрофона и радиопотоков. Wex.dsp.fft(samples) → спектр магнитуд (N/2 бинов); dominantFreq(samples, rate) → сильнейшая частота в Гц; уровень rms/peak; окно hann(n). Чистая математика, работает и headless.

Composes the Wex.dsp primitives into a reusable pipeline you declare once and re-run on every block — the DSP surface for RF, audio and sensor analysis. graph{ stages } takes an ordered list of "name:arg" stages: window:hann|hamming, decimate:N, normalize, clip:X, fft (alias magnitude), rms, peak, dominant, peaks:N. g:process(samples, rate?) runs them over a sample array (rate defaults to 44100) and returns a table with whatever the stages produced — samples (the transformed time-domain signal), mag (spectrum magnitude bins), rms, peak, dominant (Hz), peaks (top-N { bin, freq, mag }). Pure and stateless per call, so it runs anywhere — foreground, headless or a worker. Feed it blocks from Wex.audio.record, an SDR/driver, or any sample source to build a live spectrum or a tone / FSK detector.

Собирает примитивы Wex.dsp в переиспользуемый конвейер, который объявляешь один раз и прогоняешь на каждом блоке — surface DSP для RF, аудио и сенсоров. graph{ stages } принимает упорядоченный список стадий "name:arg": window:hann|hamming, decimate:N, normalize, clip:X, fft (алиас magnitude), rms, peak, dominant, peaks:N. g:process(samples, rate?) прогоняет их по массиву сэмплов (rate по умолчанию 44100) и возвращает таблицу с тем, что произвели стадии — samples (преобразованный сигнал во временной области), mag (бины спектра), rms, peak, dominant (Гц), peaks (топ-N { bin, freq, mag }). Чистый и без состояния между вызовами, поэтому работает где угодно — на переднем плане, headless или в worker. Подавай блоки из Wex.audio.record, SDR/драйвера или любого источника сэмплов, чтобы строить живой спектр или детектор тона / FSK.

local g = Wex.dsp.graph{ "window:hann", "fft", "peaks:3", "dominant" }

-- feed it blocks of samples (from Wex.audio.record, an SDR driver, a sensor…)
Wex.audio.record({ rate = 44100, frame = 2048, raw = true }, function(block)
  local r = g:process(block.pcm, 44100)
  Wex.log(("dominant %.0f Hz"):format(r.dominant))
  for _, p in ipairs(r.peaks) do Wex.log(("  peak %.0f Hz"):format(p.freq)) end
end)

A declarative binary-protocol DSL — compose byte-aligned layer schemas to build and parse packets (a lightweight Scapy inside Lua), for RF, networking and hardware-bus diagnostics. layer(name, fields) registers a schema and RETURNS a constructor; each field is { name, type, { default, compute, len } } with types u8 / i8 / u16be / u16le / u24be / u32be / u32le / mac / ip4 / bytes. build{ CtorA{…}, CtorB{…} } fills a buffer and resolves computed fields — compute = "auto_len" (length from that layer to the end), "ipv4_checksum" / "checksum16", "crc16" (CCITT) or "sum8". The packet handle gives :bytes() (a binary string to hand a driver or socket), :hex(), :base64(), :len(). parse("Eth/IPv4", bytes) decodes into a nested table (v.IPv4.ttl). Pure — it synthesises and parses bytes, it never transmits; egress stays a separate, capability-gated act. Available in the foreground bridge and in headless / worker contexts.

Декларативный DSL бинарных протоколов — из байт-выровненных схем-слоёв собираешь и разбираешь пакеты (лёгкий Scapy внутри Lua), для RF, сетевой и аппаратно-шинной диагностики. layer(name, fields) регистрирует схему и ВОЗВРАЩАЕТ конструктор; каждое поле — { name, type, { default, compute, len } } с типами u8 / i8 / u16be / u16le / u24be / u32be / u32le / mac / ip4 / bytes. build{ CtorA{…}, CtorB{…} } заполняет буфер и вычисляет поля — compute = "auto_len" (длина от этого слоя до конца), "ipv4_checksum" / "checksum16", "crc16" (CCITT) или "sum8". Хендл пакета даёт :bytes() (бинарная строка для драйвера или сокета), :hex(), :base64(), :len(). parse("Eth/IPv4", bytes) разбирает во вложенную таблицу (v.IPv4.ttl). Чистый — синтезирует и разбирает байты, но не передаёт; отправка — отдельное действие под разрешением. Доступен и на переднем плане, и в headless / worker.

local Eth = Wex.packet.layer("Eth", {
  { "dst", "mac" }, { "src", "mac" }, { "type", "u16be", { default = 0x0800 } },
})
local IPv4 = Wex.packet.layer("IPv4", {
  { "ver_ihl", "u8", { default = 0x45 } }, { "tos", "u8" },
  { "len", "u16be", { compute = "auto_len" } }, { "id", "u16be" }, { "frag", "u16be" },
  { "ttl", "u8", { default = 64 } }, { "proto", "u8" },
  { "csum", "u16be", { compute = "ipv4_checksum" } }, { "src", "ip4" }, { "dst", "ip4" },
})

local pkt = Wex.packet.build{
  Eth{ dst = "ff:ff:ff:ff:ff:ff", src = "02:11:22:33:44:55" },
  IPv4{ src = "10.0.0.2", dst = "10.0.0.1", proto = 17 },
}
Wex.log(pkt:hex())                          -- len + checksum filled in automatically

local v = Wex.packet.parse("Eth/IPv4", pkt:bytes())
Wex.log(v.IPv4.ttl .. " → " .. v.IPv4.dst)  -- 64 → 10.0.0.1

One-shot / repeating callbacks on the main thread.

Одноразовые / повторяющиеся колбэки в главном потоке.

• msdelay / period in milliseconds.задержка / период в миллисекундах.
• fnthe callback.колбэк.
• cancelTimer(id)stops a timer by its id.останавливает таймер по id.

returnsвозвращаетan id you pass to cancelTimer.id, который передаёшь в cancelTimer.

local id = Wex.interval(1000, tick)
Wex.cancelTimer(id)

Schedule Plugin.background() periodically via WorkManager. Runs with the UI closed.

Планирует Plugin.background() периодически через WorkManager. Работает при закрытом UI.

• minutesperiod; minimum 15.период; минимум 15.

Wex.background.enable(15)

Local notification.

Локальное уведомление.

• opts{ id, title, body }.{ id, title, body }.
• idinteger to update / cancel later.целое, чтобы обновить / отменить позже.

Wex.notifications.show({ id = 1, title = "Done", body = "ok" })

Write / read the system clipboard.

Записать / прочитать системный буфер обмена.

returnsвозвращаетget() → the clipboard text.get() → текст буфера.

Wex.clipboard.set("copied")

Open a link; share text via the system sheet; brief message; write to the plugin log (viewable in the manager).

Открыть ссылку; поделиться текстом системным шитом; короткое сообщение; запись в лог плагина (виден в менеджере).

Wex.log("started")
Wex.share("check this")

Quick alert. For interactive dialogs use ui:dialog / confirm / prompt.

Быстрый алерт. Для интерактивных — ui:dialog / confirm / prompt.

Wex.dialog("Note", "Saved")

Global single-input dialog — works anywhere, not only inside a ui builder.

Глобальный диалог с одним полем — работает где угодно, не только внутри ui.

• opts{ title, hint, default } (or just a title string).{ title, hint, default } (или просто строка-заголовок).
• fn(text)the entered text on OK, nil on cancel.введённый текст по OK, nil при отмене.

Wex.prompt({ title = "Name" }, function(t) Wex.toast(t) end)

Global Yes / No dialog.

Глобальный диалог Да / Нет.

• fn(ok)boolean: true = confirmed.boolean: true = подтвердил.

Wex.confirm({ title = "Delete?" }, function(ok) if ok then run() end end)

Haptic buzz for ms milliseconds (1–5000).

Виброотклик на ms миллисекунд (1–5000).

Wex.vibrate(40)

Asks the user for a fingerprint or face — or, with allowDeviceCredential = true, the device PIN / pattern / password — to gate a screen or a stored secret. fn gets { ok = true } on success, or { ok = false, error } when the user cancels or it fails. canAuthenticate() reports whether the device can authenticate right now (hardware present and something enrolled). It uses a weak biometric class: right for gating access, not for unlocking a crypto key. No permission needed — the user always completes the prompt themselves. Foreground plugins only.

Просит у пользователя отпечаток или лицо — либо, при allowDeviceCredential = true, PIN / графический ключ / пароль устройства — чтобы закрыть экран или хранимый секрет. fn получает { ok = true } при успехе или { ok = false, error }, если пользователь отменил или не прошёл. canAuthenticate() сообщает, может ли устройство аутентифицировать прямо сейчас (есть железо и что-то настроено). Используется слабый биометрический класс: годится для ограничения доступа, но не для разблокировки крипто-ключа. Разрешение не нужно — пользователь всегда сам проходит запрос. Только для плагинов на переднем плане.

if Wex.auth.canAuthenticate({ deviceCredential = true }) then
  Wex.auth.biometric({ title = "Unlock notes", allowDeviceCredential = true }, function(r)
    if r.ok then openNotes() else Wex.toast(r.error or "cancelled") end
  end)
end

Current battery state.

Текущее состояние батареи.

returnsвозвращает{ level = 0–100, charging = bool }.{ level = 0–100, charging = bool }.

local b = Wex.battery()
Wex.toast(b.level .. "%")

Read-only info tables — the same spacing/radius scale the ui: token strings ("sm"/"md"/…) resolve to, as plain numbers for custom math.

Таблицы информации (только чтение) — та же шкала spacing/radius, к которой приводятся строки-токены ui: ("sm"/"md"/…), но как числа для собственных расчётов.

• theme{ surface, onSurface, primary, error, … } hex colors; theme.spacing / theme.radius / theme.font = the token scales as numbers (dp/sp).{ surface, onSurface, primary, error, … } hex-цвета; theme.spacing / theme.radius / theme.font — те же шкалы токенов числами (dp/sp).
• device{ model, manufacturer, sdk, release, lang }.{ model, manufacturer, sdk, release, lang }.

ui:text(""):color(Wex.theme.primary)
local gap = Wex.theme.spacing.lg -- 16

Captures the microphone as raw PCM. Each frame's data has rms and peak (level), rate, and — opt-in — spectrum (magnitudes, with fft=true) or pcm (normalised samples, with raw=true). For spectrum analysers, acoustic detectors, sonar and FSK/Morse decoders. Needs Plugin.permissions = { "microphone" }.

Захватывает микрофон как сырой PCM. У каждого кадра data есть rms и peak (уровень), rate и — по желанию — spectrum (магнитуды, при fft=true) или pcm (нормализованные сэмплы, при raw=true). Для спектроанализаторов, акустических детекторов, сонара и декодеров FSK/Морзе. Нужно Plugin.permissions = { "microphone" }.

Floating windows over other apps, built from the same ui: toolkit — diagnostic widgets, dashboards, on-screen controls. The window is draggable by default; :hide() removes it. canDraw() checks the OS grant and request() opens the settings screen to allow it. Needs Plugin.permissions = { "overlay" }.

Плавающие окна поверх других приложений, собранные из того же ui:-тулкита — диагностические виджеты, панели, экранные кнопки. Окно по умолчанию перетаскивается; :hide() убирает его. canDraw() проверяет разрешение ОС, request() открывает экран настроек. Нужно Plugin.permissions = { "overlay" }.

Scans QR codes and barcodes through a full-screen viewfinder (framework Camera2 + zxing, no native library). fn receives { text, format } for each decode; once=true (default) closes after the first, facing="front"/"back". :stop() closes it. Needs Plugin.permissions = { "camera" }.

Сканирует QR-коды и штрихкоды через полноэкранный видоискатель (встроенный Camera2 + zxing, без нативных библиотек). fn получает { text, format } на каждый декод; once=true (по умолчанию) закрывает после первого, facing="front"/"back". :stop() закрывает. Нужно Plugin.permissions = { "camera" }.

Takes one still photo through the system camera app and hands back a real file path — feed it straight to Wex.image.load. fn gets { ok, path } (path is present only when ok is true; ok is false if the user cancels or no camera app is available). The plugin owns the file — it lands in the plugin's own scoped folder, so nothing is written to the shared gallery. name optionally sets the filename. Foreground plugins only. Needs Plugin.permissions = {"camera"}.

Делает один снимок через системное приложение камеры и возвращает настоящий путь к файлу — его можно сразу передать в Wex.image.load. fn получает { ok, path } (path есть только при ok = true; ok = false, если пользователь отменил съёмку или приложения камеры нет). Файл принадлежит плагину — он попадает в его собственную scoped-папку, в общую галерею ничего не пишется. name по желанию задаёт имя файла. Только для плагинов на переднем плане. Нужно Plugin.permissions = {"camera"}.

Plugin.permissions = { "camera" }

Wex.camera.capture(function(r)
  if r.ok then
    local img = Wex.image.load(r.path)
    Wex.log("captured " .. img:width() .. "x" .. img:height())
  end
end)

Decode, transform and re-encode a bitmap so you can downscale/crop/rotate a picked or captured image before uploading or showing it. src is "asset:…", a Wex.files path, a data: URI or base64. The ops chain and mutate the working bitmap; :toBase64/:toDataUri/:save("name.jpg") produce the result (fmt = jpeg|png|webp, q = 1..100) and :exif() reads orientation/date/make/model/GPS. Decoding is capped at 4096 px so a huge source can't OOM. Works in the foreground and in a background job.

Декодирует, преобразует и перекодирует битмап, чтобы уменьшить/обрезать/повернуть выбранное или снятое изображение перед загрузкой или показом. src — "asset:…", путь в Wex.files, data: URI или base64. Операции — цепочкой, меняют рабочий битмап; :toBase64/:toDataUri/:save("name.jpg") дают результат (fmt = jpeg|png|webp, q = 1..100), а :exif() читает ориентацию/дату/производителя/модель/GPS. Декодирование ограничено 4096 px, чтобы не словить OOM. Работает на переднем плане и в фоне.

local img = Wex.image.load("asset:photo.jpg")
img:rotate(90):thumbnail(512)
ui:image(img:toDataUri("jpeg", 80))
img:save("thumb.jpg")

The camera flashlight/LED — no permission required. available() is false on a device with no flash; on()/off()/toggle() return the new on-state. The torch is turned off automatically when the plugin closes.

Фонарик/LED камеры — разрешение не нужно. available() — false, если вспышки нет; on()/off()/toggle() возвращают новое состояние. При закрытии плагина фонарик гасится автоматически.

if Wex.torch.available() then
  ui:switch("Flashlight", false, function(on) Wex.torch.toggle() end)
end

Fire an Android intent — one API for call, maps, share, opening a link, launching an app or a specific activity.

Отправить Android-intent — один API для звонка, карт, шаринга, открытия ссылки, запуска приложения или конкретной активности.

• action"view" / "send" / "dial" / "edit" / … or a full "android.intent.action.X"."view" / "send" / "dial" / "edit" / … или полный "android.intent.action.X".
• dataa URI — tel:, geo:, https:, mailto:, wex://plugin/…URI — tel:, geo:, https:, mailto:, wex://plugin/…
• typeMIME type (e.g. "text/plain").MIME-тип (напр. "text/plain").
• extras{ key = value } put as intent extras.{ key = value } — кладутся в extras.
• package / componenttarget an app, or "pkg/Activity".нацелить на приложение, или "pkg/Activity".

returnsвозвращаетtrue if launched, false otherwise.true если запущено, иначе false.

Wex.intent({ action = "dial", data = "tel:+123" })
Wex.intent({ action = "view", data = "geo:0,0?q=Berlin" })

Launches another app for its result. spec is the same table Wex.intent.start takes — { action, data, type, package, component, category, flags, extras }. When the app returns, fn gets { ok (true on RESULT_OK), code (the raw resultCode), uri (the result's data URI, if any), text (its EXTRA_TEXT, if any), extras (the result's string / number / boolean extras) }. Use it for a barcode scanner, a contact or document picker, a share-with-result, or any app that hands data back. One result at a time; foreground plugins only. Needs Plugin.permissions = {"intent"}.

Запускает другое приложение ради результата. spec — та же таблица, что и у Wex.intent.start: { action, data, type, package, component, category, flags, extras }. Когда приложение вернётся, fn получит { ok (true при RESULT_OK), code (сырой resultCode), uri (URI данных результата, если есть), text (его EXTRA_TEXT, если есть), extras (строковые / числовые / логические extra результата) }. Годится для сканера штрихкодов, выбора контакта или документа, «поделиться с результатом» и любого приложения, которое возвращает данные. По одному результату за раз; только для плагинов на переднем плане. Нужно Plugin.permissions = {"intent"}.

Plugin.permissions = { "intent" }

Wex.intent.startForResult({
  action = "com.google.zxing.client.android.SCAN"
}, function(r)
  if r.ok and r.extras then
    Wex.toast("scanned: " .. (r.extras.SCAN_RESULT or "?"))
  end
end)

Apps that can handle the intent, without launching anything.

Приложения, способные обработать intent, ничего не запуская.

returnsвозвращаетarray of { package, activity, label }.массив { package, activity, label }.

for _, app in ipairs(Wex.intent.query({
  action = "view", data = "https://x" })) do print(app.label) end

App version + capability detection — so a plugin degrades gracefully on older builds.

Версия приложения + детект возможностей — плагин мягко деградирует на старых сборках.

returnsвозвращаетversion: string; build: number; has: bool.version: строка; build: число; has: bool.

if Wex.has("intent") then Wex.intent(...) end
ui:text("v" .. Wex.api.version)

A link or home-screen shortcut that opens an installed plugin by its id.

Ссылка или ярлык на рабочем столе, открывающие установленный плагин по его id.

Wex.intent({ action = "view", data = "wex://plugin/notes" })

Optional hooks. onBack() returning true consumes the system Back press (e.g. to close your own panel first). onClose() runs when the plugin screen is destroyed. onResize(w, h) and onRotate(landscape) fire when the screen turns — dp, content area, not the raw display; onImmersive(on) when full screen goes on or off. Save on onPause: a rotation may restart the plugin, and the host puts the rotation and full-screen mode back before your first frame.

Необязательные хуки. onBack(), вернувший true, поглощает системный Back (например, чтобы сначала закрыть свою панель). onClose() вызывается при уничтожении экрана плагина. onResize(w, h) и onRotate(landscape) срабатывают при повороте экрана — в dp и по области контента, не по «сырому» дисплею; onImmersive(on) — при входе и выходе из полного экрана. Сохраняйтесь в onPause: поворот может перезапустить плагин, а хост вернёт ориентацию и полноэкранный режим до вашего первого кадра.

function Plugin.onResume() refresh() end
function Plugin.onResize(w, h) canvasHeight = h end
function Plugin.onBack()
  if panelOpen then panel:hide(); panelOpen = false; return true end
end

Optional hook for the predictive back gesture (Android 14+). progress goes 0→1 as the user drags the Back gesture; edge is "left", "right", or "cancel" when the gesture is released without committing. The host already peeks the screen back by default; use this to drive your own gesture-linked animation. A committed gesture then runs the normal Back (see Plugin.onBack).

Необязательный хук жеста предиктивного «назад» (Android 14+). progress идёт 0→1 по мере протягивания жеста; edge — "left", "right" или "cancel", если жест отпущен без подтверждения. Хост по умолчанию уже «отодвигает» экран; используй это для собственной анимации, привязанной к жесту. Подтверждённый жест дальше выполняет обычный Back (см. Plugin.onBack).

function Plugin.onBackPredictive(progress, edge)
  panel:alpha(1 - progress)
end

Table of arguments the plugin was opened with — from Wex.plugins.open(id, { … }), a notification's `args`, or a deep link wex://plugin/<id>?k=v.

Таблица аргументов, с которыми открыли плагин — из Wex.plugins.open(id, { … }), `args` уведомления или диплинка wex://plugin/<id>?k=v.

local host = Wex.args.host or "10.0.0.1"

Present when the plugin was opened from the system Share sheet (see Plugin.handles). action is "send" or "send_multiple"; type is the shared MIME type; every entry in files is already a copy in the plugin's folder, so Wex.files.read / readBase64 / share work on it by name. skipped counts files that were too large (24 MB) or unreadable.

Есть, когда плагин открыли из системного «Поделиться» (см. Plugin.handles). action — "send" или "send_multiple"; type — MIME переданного; каждая запись в files уже скопирована в папку плагина, так что Wex.files.read / readBase64 / share работают по имени. skipped — сколько файлов пропущено (больше 24 МБ или не читаются).

local s = Wex.args.share
if s then
  if s.text then Wex.clipboard.copy(s.text) end
  for _, f in ipairs(s.files) do
    Wex.log(f.name .. " " .. f.type .. " " .. f.size)
  end
end

Installed plugins registry (id, name, icon, version, enabled, permissions). open() launches another plugin, passing `args`.

Реестр установленных плагинов (id, name, icon, version, enabled, permissions). open() запускает другой плагин, передавая `args`.

if Wex.plugins.exists("scanner") then Wex.plugins.open("scanner", { target = ip }) end

Lists every library API importable with Wex.import right now: an array of { name, id, plugin } — one entry per Plugin.provides name of each installed, enabled plugin. Use it to discover libraries or check a dependency is present before importing.

Перечисляет все библиотечные API, доступные для Wex.import прямо сейчас: массив { name, id, plugin } — по записи на каждое имя из Plugin.provides каждого установленного включённого плагина. Годится, чтобы найти библиотеки или проверить наличие зависимости перед импортом.

for _, lib in ipairs(Wex.plugins.libraries()) do
  print(lib.name .. " (from " .. lib.plugin .. ")")
end

API level (bumped with every API extension), the list of available Wex features, and whether the script declared a permission — degrade gracefully instead of crashing. Wex.apiLevel is a shortcut for Wex.api.level.

Уровень API (растёт с каждым расширением), список доступных возможностей Wex и проверка объявленного разрешения — деградируйте мягко, а не падайте. Wex.apiLevel — короткий алиас для Wex.api.level.

returnsвозвращаетlevel: number; features: array; has/can: bool.level: число; features: массив; has/can: bool.

if Wex.api.level >= 2 and Wex.has("tcp") then … end
if not Wex.can("network") then ui:banner("Offline mode", "warning") end

Own plugin id, granted permissions, whether running in Plugin.background(), device language and a one-line localizer.

Свой id плагина, выданные разрешения, признак запуска в Plugin.background(), язык устройства и однострочный локализатор.

ui:title(Wex.tr({ en = "Settings", ru = "Настройки" }))

Asks the launcher to pin a home-screen shortcut that opens this plugin (uses the plugin's avatar as the icon).

Просит лаунчер закрепить ярлык на рабочем столе, открывающий этот плагин (иконка — аватар плагина).

returnsвозвращаетtrue if the request was shown.true, если запрос показан.

ui:button("Add to home screen", function() Wex.shortcut() end)

Runs a Lua source string on a background thread with a fresh pure sandbox (Wex.dsp/bit/hash/crypto/json/str/…, no UI or IO) — no 4-second UI watchdog, for parsing big dumps, heavy crypto and DSP. `args` is passed in via JSON as the global `args`; the return value comes back through a promise: :next(fn(result)) / :catch(fn(err)). Both fire on the main thread.

Выполняет строку Lua-кода в фоновом потоке в свежей чистой песочнице (Wex.dsp/bit/hash/crypto/json/str/…, без UI и IO) — без 4-секундного watchdog, для разбора больших дампов, тяжёлой криптографии и DSP. `args` передаётся через JSON как глобальный `args`; результат возвращается промисом: :next(fn(result)) / :catch(fn(err)). Оба вызываются на главном потоке.

A true foreground service that keeps running with a persistent notification after the UI closes — continuous telemetry, an on-device server, long-lived beacons — instead of the 15-minute Plugin.background() quantum. Wex.service.start runs your Plugin.service() on a background thread where its timers Wex.every(ms, fn) / Wex.after(ms, fn) / Wex.cancel(id) keep firing; Wex.service.notify(title, text) updates the notification; Wex.service.stop() ends it. Needs Plugin.permissions = { "background" }. On HyperOS/OneUI and custom kernels the OS may still doze a foreground service with the screen off — call Wex.service.requestUnrestricted() (checks Wex.service.isBatteryOptimized() first) to ask the user to exempt the app from battery optimization.

Настоящий foreground-сервис, который продолжает работать с постоянным уведомлением после закрытия UI — непрерывная телеметрия, сервер на устройстве, долгоживущие маяки — вместо 15-минутного кванта Plugin.background(). Wex.service.start запускает твой Plugin.service() в фоновом потоке, где его таймеры Wex.every(ms, fn) / Wex.after(ms, fn) / Wex.cancel(id) продолжают срабатывать; Wex.service.notify(title, text) обновляет уведомление; Wex.service.stop() завершает. Нужно Plugin.permissions = { "background" }. На HyperOS/OneUI и кастомных ядрах система может усыплять foreground-сервис при выключенном экране — вызови Wex.service.requestUnrestricted() (сначала проверь Wex.service.isBatteryOptimized()), чтобы попросить пользователя исключить приложение из оптимизации батареи.

Heading with level 1–3; Markdown (headings, **bold**, *italic*, `code`, lists, links, quotes); a pretty-printed JSON viewer of any table.

Заголовок уровня 1–3; Markdown (заголовки, **жирный**, *курсив*, `код`, списки, ссылки, цитаты); красиво отформатированный JSON любой таблицы.

ui:markdown("## Report\n- **ok**: 12\n- *failed*: 1")
ui:json(res.json)

A scrolling monospace log panel. t:append(line, color?) / t:info / t:ok / t:warn / t:error / t:clear() / t:get() / t:copy() / t:autoScroll(bool). Appends are collected and rendered once per frame, so a serial console at 115200 baud stays readable instead of re-laying out the view on every line.

Прокручиваемая моноширинная лог-панель. t:append(line, color?) / t:info / t:ok / t:warn / t:error / t:clear() / t:get() / t:copy() / t:autoScroll(bool). Добавления накапливаются и отрисовываются раз в кадр, поэтому последовательная консоль на 115200 бод остаётся отзывчивой вместо перелейаута на каждую строку.

• heightdp, default 240.dp, по умолчанию 240.
• maxLinesring buffer size (default 500).размер кольцевого буфера (по умолчанию 500).

local term = ui:terminal({ height = 260 })
term:info("connecting…")
term:ok("200 OK")
term:error("timeout")

A Material list row: leading emoji/icon/avatar initials, title + subtitle, trailing text or badge, chevron. h:title/subtitle/trailing/badge(text, tone).

Строка списка в стиле Material: эмодзи/иконка/инициалы слева, заголовок + подзаголовок, текст или бейдж справа, шеврон. h:title/subtitle/trailing/badge(text, tone).

ui:item({ icon = "wifi", title = "Office AP", subtitle = "-52 dBm · ch 36", badge = "WPA3", tone = "success",
  onClick = function() open(ap) end })

Square tappable tiles and an equal-width grid (1–6 columns). The grid builder receives a `cell` ui, the 1-based index and the item.

Квадратные плитки и сетка равных колонок (1–6). Билдер сетки получает `cell` ui, индекс с 1 и элемент.

ui:grid(3, tools, function(cell, i, t)
  cell:tile(t.icon, t.name, function() run(t) end)
end, "sm")

KPI card: small label, big value, optional delta pill. h:set(v) / h:delta(text, tone) / h:bind(key, fmt?).

KPI-карточка: подпись, крупное значение, необязательная плашка дельты. h:set(v) / h:delta(text, tone) / h:bind(key, fmt?).

ui:row(function(r)
  r:stat("Latency", "23 ms", { delta = "-4 ms", tone = "success" }):grow()
  r:stat("Loss", "0.2%", { tone = "warning" }):grow()
end, "sm")

Tinted inline message with an optional action; a stage indicator (s:set(i) / s:next() / s:prev()).

Подсвеченное встроенное сообщение с действием; индикатор этапов (s:set(i) / s:next() / s:prev()).

ui:banner("Update available", "info", "Install", update)
local s = ui:steps({ "Scan", "Select", "Done" }, 1)

Initials avatar (hashed color) or circular image; a spinner with text (l:text(s), l:done("✓"), l:hide()); a compact icon-only button.

Аватар с инициалами (цвет по хешу) или круглая картинка; спиннер с текстом (l:text(s), l:done("✓"), l:hide()); компактная кнопка-иконка.

local l = ui:loading("Fetching…")
Wex.http(u, function(r) l:done("Loaded") end)

Specialised inputs. search debounces fn as the user types and fires immediately on the keyboard's search key; number:get() returns text, :number() returns a number.

Специализированные поля. search вызывает fn с задержкой при вводе и сразу — по клавише поиска; number:get() возвращает текст, :number() — число.

ui:search("Filter", function(q) list:count(#filter(q)) end)
local port = ui:number("Port", 443)
print(port:number())

Multi-select chips; a segmented control (exclusive, always visible); a star rating. segmented calls fn(initial, label) once inside the constructor (initial defaults to 1) and again on :set(i) — see «Callbacks fire during creation».

Мульти-выбор чипов; сегментированный контрол (один из, всегда видим); звёздный рейтинг. segmented вызывает fn(initial, label) один раз внутри конструктора (initial по умолчанию 1) и снова при :set(i) — см. «Callbacks fire during creation».

ui:segmented({ "GET", "POST" }, function(i, m) method = m end, 1)

Date / time pickers rendered as outlined buttons. Handles: :get() / :set() / :text().

Пикеры даты / времени в виде контурных кнопок. Хендлы: :get() / :set() / :text().

ui:date("From", nil, function(ms, s) from = ms end)

Declarative form. Field: { name, type, label, default, options, min, max, step, required, helper, icon }. Types: text password number int email url phone textarea switch checkbox dropdown chips multiChips segmented radio slider stepper date time rating title subtitle label. f:values() / f:get(name) / f:set(name, v) / f:error(name, msg) / f:valid() / f:field(name) / f:clear().

Декларативная форма. Поле: { name, type, label, default, options, min, max, step, required, helper, icon }. Типы: text password number int email url phone textarea switch checkbox dropdown chips multiChips segmented radio slider stepper date time rating title subtitle label. f:values() / f:get(name) / f:set(name, v) / f:error(name, msg) / f:valid() / f:field(name) / f:clear().

ui:form({
  { name = "host", label = "Host", required = true },
  { name = "port", type = "number", default = 22 },
  { name = "tls", type = "switch", label = "TLS", default = true },
  { name = "mode", type = "dropdown", options = { "fast", "deep" } },
}, "Connect", function(v) connect(v.host, v.port, v.tls) end)

Tabs rebuild their content on every switch (t:select(i), t:get(), t:refresh(), t:badge(i, n)). Expander is a collapsible card whose content builds lazily on first open (e:open/close/toggle/isOpen).

Вкладки перестраивают содержимое при каждом переключении (t:select(i), t:get(), t:refresh(), t:badge(i, n)). Expander — сворачиваемая карточка, содержимое строится лениво при первом открытии (e:open/close/toggle/isOpen).

ui:tabs({ "Status", "Log" }, function(c, i)
  if i == 1 then status(c) else c:terminal({ lines = Wex.log.lines() }) end
end)

Horizontal scrolling row (cards, chips, tiles); a data table with header row, striped rows and row taps. Rows are arrays or { col = value } tables. h:set(rows) / h:add(row) / h:clear().

Горизонтально прокручиваемая строка (карточки, чипы, плитки); таблица данных с шапкой, полосатыми строками и тапами. Строки — массивы или таблицы { col = value }. h:set(rows) / h:add(row) / h:clear().

ui:table({ headers = { "Host", "RTT" }, rows = { { "1.1.1.1", "12 ms" } },
  onRow = function(i, row) ui:toast(row[1]) end })

Native charts: bar, hbar, line, area, spark, pie, donut. c:set(values, labels?) / c:push(v, label?) for live series (keeps maxPoints) / c:labels / c:colors / c:type / c:clear. Passing a plain array draws bars. c:push(value, label) appends one point and drops the oldest past maxPoints; it is meant for live feeds and costs one insert, with the repaint left to the next frame, so a burst of a thousand samples between two frames still paints once.

Нативные графики: bar, hbar, line, area, spark, pie, donut. c:set(values, labels?) / c:push(v, label?) для живых серий (хранит maxPoints) / c:labels / c:colors / c:type / c:clear. Простой массив рисует столбцы. c:push(value, label) добавляет точку и выбрасывает самую старую после maxPoints; он рассчитан на живой поток, стоит одну вставку, а перерисовка откладывается до следующего кадра, поэтому пачка из тысячи отсчётов между двумя кадрами рисуется один раз.

local rtt = ui:chart({ type = "spark", values = {}, maxPoints = 40, color = "#38BDF8" })
Wex.interval(1000, function() rtt:push(measure()) end)

Immediate-mode drawing, all coordinates in dp. The handle draws (line, rect, circle, arc, polygon, path, text, fill, stroke, color, clear, redraw) and animates with d:loop(fps, fn(d, dt, t)). onTouch reports every finger: phase is down, pointerdown, move, pointerup, up or cancel, and p is the pointer table — p.count, p[i].x / p[i].y / p[i].id, and for two fingers p.scale (pinch, relative to the moment the second finger landed), p.panX, p.panY, p.distance, p.midX, p.midY and p.angle. That is enough for a pan-and-zoom spectrum view or an oscilloscope without dropping to native code.

Рисование в режиме немедленного вывода, все координаты в dp. Хендл рисует (line, rect, circle, arc, polygon, path, text, fill, stroke, color, clear, redraw) и анимирует через d:loop(fps, fn(d, dt, t)). onTouch сообщает о каждом пальце: phase — это down, pointerdown, move, pointerup, up или cancel, а p — таблица касаний: p.count, p[i].x / p[i].y / p[i].id, а для двух пальцев p.scale (щипок относительно момента, когда лёг второй палец), p.panX, p.panY, p.distance, p.midX, p.midY и p.angle. Этого хватает на анализатор спектра с зумом или осциллограф без перехода на нативный код.

local zoom, offset = 1, 0
ui:canvas(240, function(d)
  d:color("primary")
  for i = 1, 64 do d:line(i * 4 * zoom + offset, 220, i * 4 * zoom + offset, 220 - bins[i]) end
end):onTouch(function(x, y, phase, p)
  if p.count >= 2 then
    zoom = p.scale
    offset = p.panX
    d:redraw()
  end
end)

The drawing calls on a canvas handle, all in dp. State first, shape second: color, alpha, stroke(width), fill(), outline(), style("fill"|"stroke") and font(size, bold, align) set how the next shapes are painted. path takes a flat list of x, y numbers. Each call adds one operation to the frame; redraw() paints it, and clear() starts a new frame.

Рисующие вызовы у хендла canvas, всё в dp. Сначала состояние, потом фигура: color, alpha, stroke(ширина), fill(), outline(), style("fill"|"stroke") и font(размер, жирный, выравнивание) задают, чем будут нарисованы следующие фигуры. path принимает плоский список чисел x, y. Каждый вызов добавляет операцию в кадр; redraw() его рисует, а clear() начинает новый.

returnsвозвращаетthe same handle, so the calls chainтот же хендл, вызовы можно объединять в цепочку

ui:canvas(200, function(d)
  d:grid(20)
  d:color("primary"):stroke(2)
  d:path({ 0, 100, 40, 60, 80, 120, 120, 30 }, false)
  d:color("warning"):fill()
  d:circle(120, 30, 4)
  d:font(12, true, "left"):text("peak", 128, 34)
end)

Embedded WebView. HTML snippets need no permission; http(s) pages need "network". With js = true the page can call `Wex.send(text)` (→ w:onMessage(fn)) and w:eval(js, fn(result)) runs JavaScript. height takes dp or "match". `fullscreen = true` is the game preset: immersive host, one-viewport size, page keeps every gesture, screen stays on. w:load(s) / w:back() / w:reload() / w:onLoad(fn) / w:post(text) / w:fullscreen(bool) / w:orientation(mode) / w:grab(bool) / w:keepAwake(bool) / w:size() / w:focus().

Встроенный WebView. HTML-фрагменты без разрешений; http(s)-страницы требуют "network". С js = true страница может вызывать `Wex.send(text)` (→ w:onMessage(fn)), а w:eval(js, fn(result)) выполняет JavaScript. height принимает dp или "match". `fullscreen = true` — игровой режим: хост уходит в полный экран, вью ровно на один вьюпорт, все жесты остаются странице, экран не гаснет. w:load(s) / w:back() / w:reload() / w:onLoad(fn) / w:post(text) / w:fullscreen(bool) / w:orientation(mode) / w:grab(bool) / w:keepAwake(bool) / w:size() / w:focus().

local w = ui:web("asset:game.html", { height = "match", js = true, fullscreen = true })
w:onMessage(function(m) ui:toast(m) end)
w:post("hello page")   -- → window.onWexMessage("hello page")

Structured request/response between a ui:web page and Lua — local pages with js = true. In the page, Wex.call(method, args) returns a Promise; in Lua, w:handle(method, fn) answers it. The handler gets the decoded args and either returns the result (which resolves the Promise) or, for async work, takes a second respond argument and calls respond(result) whenever it is ready. An error thrown in the handler rejects the Promise; calling an unregistered method rejects too. args and the result cross as JSON, so pass plain tables/values. A remote (http/https) page can never reach a handler. The older fire-and-forget channels — Wex.send(msg)/w:onMessage and w:eval(js, cb) — still work alongside it.

Структурный запрос-ответ между страницей ui:web и Lua — для локальных страниц с js = true. На странице Wex.call(method, args) возвращает Promise; в Lua на него отвечает w:handle(method, fn). Обработчик получает разобранные args и либо возвращает результат (он разрешает Promise), либо для асинхронной работы принимает второй аргумент respond и вызывает respond(result), когда будет готов. Исключение в обработчике отклоняет Promise; вызов незарегистрированного метода — тоже. args и результат передаются как JSON, поэтому передавайте простые таблицы/значения. Удалённая (http/https) страница до обработчика не дотянется. Прежние каналы «выстрелил-и-забыл» — Wex.send(msg)/w:onMessage и w:eval(js, cb) — продолжают работать рядом.

local w = ui:web([[
  <button onclick="go()">refresh</button>
  <script>
    async function go() {
      const s = await Wex.call("stats", { tag: "x" })
      document.title = s.total
    }
  </script>
]], { js = true })

w:handle("stats", function(a)
  return { total = 42, tag = a.tag }   -- the returned table resolves the page Promise
end)

Inline video playback. src is "asset:…", a Wex.files path, or an http(s) URL (needs Plugin.permissions = {"network"}). controls shows the scrubber; loop/autoplay/mute are booleans; height is dp. The handle drives playback.

Встроенное воспроизведение видео. src — "asset:…", путь в Wex.files или http(s)-URL (нужно Plugin.permissions = {"network"}). controls показывает перемотку; loop/autoplay/mute — булевы; height в dp. Хендл управляет воспроизведением.

returnsвозвращаетa handle: v:play(), v:pause(), v:seek(ms), v:position(), v:duration(), v:mute(bool), v:onEnd(fn).хендл: v:play(), v:pause(), v:seek(ms), v:position(), v:duration(), v:mute(bool), v:onEnd(fn).

local v = ui:video("asset:intro.mp4", { height = 200, controls = true })
ui:button("Play", function() v:play() end)

A canvas/WebGL page becomes playable with three settings: `fullscreen = true` (toolbar and system bars go, a notch pill with the plugin name and ✕ takes their place), height "match" (exactly one viewport, so the host has nothing left to scroll) and the default gesture grab (a look-stick drag no longer drags the layout). Inside a LOCAL page (snippet or package asset) window.Wex also has: send(text), log(text), get(key), set(key, value) — the plugin's own storage, toast(text), vibrate(ms), fullscreen(bool), orientation(mode), keepAwake(bool), viewport() → JSON. A remote http(s) page only gets send/log.

Страница с canvas/WebGL становится играбельной от трёх настроек: `fullscreen = true` (тулбар и системные бары уходят, вместо них — «челка» с названием плагина и ✕), height "match" (ровно один вьюпорт, хосту нечего скроллить) и захват жестов по умолчанию (свайп обзора больше не тащит лайаут). В ЛОКАЛЬНОЙ странице (фрагмент или ассет пакета) у window.Wex есть ещё: send(text), log(text), get(key), set(key, value) — то же хранилище плагина, toast(text), vibrate(ms), fullscreen(bool), orientation(mode), keepAwake(bool), viewport() → JSON. Внешней http(s)-странице достаются только send/log.

-- Lua
Wex.screen.orientation("landscape")
local w = ui:web("asset:game.html", { js = true, fullscreen = true })

-- в самой странице
-- Wex.set("world", JSON.stringify(state))
-- const saved = Wex.get("world")
-- window.onWexMessage = function(text) { … }

Floating action button; toolbar action buttons for the current screen (icon names or emoji); a popup menu anchored to the last widget.

Плавающая кнопка; кнопки действий в тулбаре текущего экрана (имена иконок или эмодзи); всплывающее меню у последнего виджета.

ui:actions({ { label = "Refresh", icon = "refresh", onClick = reload }, { label = "Help", icon = "info", onClick = help } })
ui:fab("bolt", scan, "Scan")

A Material 3 split button: a primary action attached to a menu trigger that drops the alternatives. style is "filled" (default), "tonal", "outlined", "danger" or "success".

Split-кнопка Material 3: основное действие плюс триггер меню с вариантами. style — "filled" (по умолчанию), "tonal", "outlined", "danger" или "success".

returnsвозвращаетa handle: h:text(s), h:onClick(fn), h:items(list).хендл: h:text(s), h:onClick(fn), h:items(list).

ui:splitButton({
  label = "Run", style = "tonal",
  onClick = function() start() end,
  items = { "Fast", "Thorough" },
  onSelect = function(i, name) ui:toast(name) end,
})

A rounded, elevated pill of quick actions — the Material 3 floating-toolbar look — centred and sized to its contents. Each action is an icon button with a tooltip label.

Скруглённая приподнятая «пилюля» быстрых действий — вид floating toolbar из Material 3 — по центру и по размеру содержимого. Каждое действие — иконка-кнопка с подсказкой-подписью.

ui:floatingToolbar({ actions = {
  { icon = "refresh", label = "Reload", onClick = function() reload() end },
  { icon = "share", label = "Share", onClick = function() share() end },
} })

Toolbar title/subtitle, close the plugin, scroll the page, hide the keyboard, number of widgets on this ui, style handle of the last one.

Заголовок/подзаголовок тулбара, закрыть плагин, прокрутить страницу, скрыть клавиатуру, число виджетов на этом ui, хендл последнего.

ui:setSubtitle("connected · " .. host)

Snackbar with an action; simple alert; a quick bottom-sheet list of actions.

Снекбар с действием; простой алерт; быстрый нижний список действий.

ui:sheetList("Host", { "Ping", "Ports", "Copy IP" }, function(i) … end)

Dialog options grew: custom button labels, danger styling, typed prompts (number → returns a number), keepOpen = true keeps ui:dialog open while onPositive returns false (validation).

Диалоги получили опции: подписи кнопок, стиль danger, типизированный prompt (number → число), keepOpen = true держит ui:dialog открытым, пока onPositive возвращает false (валидация).

ui:confirm("Delete all?", wipe, { yes = "Delete", danger = true })
ui:prompt("Port", "1-65535", function(n) end, { type = "number", default = "22" })

A bold gradient header block: large title, subtitle and an optional icon, centred on a two-colour gradient (theme roles or #hex). The text colour is picked automatically for contrast. Great as the top of a screen.

Яркий градиентный заголовочный блок: крупный заголовок, подзаголовок и необязательная иконка по центру двухцветного градиента (роли темы или #hex). Цвет текста подбирается автоматически для контраста. Отлично смотрится вверху экрана.

A circular progress ring with a value in the centre and a caption under it. h:set(value, label?) / h:label(s) / h:caption(s) / h:color(c) update it live — perfect for dashboards (CPU, battery, score). ui:ring is an alias.

Круговое кольцо прогресса со значением в центре и подписью под ним. h:set(value, label?) / h:label(s) / h:caption(s) / h:color(c) обновляют его на лету — идеально для дашбордов (CPU, батарея, счёт). ui:ring — псевдоним.

An inline mini-chart from a list of numbers, no axes. type line/area/bar, optional fill. h:set(numbers) redraws it and h:color(c) recolours — cheap enough to update on a timer.

Компактный мини-график из списка чисел, без осей. type line/area/bar, необязательная заливка. h:set(numbers) перерисует, h:color(c) перекрасит — достаточно дёшево, чтобы обновлять по таймеру.

A shimmering placeholder shown while data loads: N bars with an animated sweep. Swap it for the real content once your fetch returns — feels faster than a bare spinner.

Мерцающий плейсхолдер на время загрузки: N полос с бегущим бликом. Замени его на реальный контент, когда придут данные — ощущается быстрее, чем голый спиннер.

A vertical event rail: a coloured dot and connecting line per item, with time, bold title and body text. Good for history, activity feeds and step-by-step results.

Вертикальная лента событий: цветная точка и соединительная линия у каждого пункта, время, жирный заголовок и текст. Подходит для истории, лент активности и пошаговых результатов.

A group of collapsible sections where opening one closes the others. Each section’s build(ui) fills its body with any widgets. Set open=true to expand one at start.

Группа сворачиваемых секций, где открытие одной закрывает остальные. build(ui) каждой секции наполняет её тело любыми виджетами. open=true раскрывает одну на старте.

Swipeable, snapping pages built on the fly: pass a list (or a count) and a builder that fills each page(ui). Dot indicators track the current page. Great for onboarding, galleries and cards.

Свайпаемые страницы с прилипанием, строятся на лету: передай список (или число) и билдер, наполняющий каждую page(ui). Точки-индикаторы показывают текущую страницу. Хорошо для онбординга, галерей и карточек.

An editable set of chips: type and press Done to add, tap ✕ to remove. onChange(tags) fires on every change; h:tags() reads them, h:add(s) / h:clear() edit them.

Редактируемый набор чипов: введи и нажми Готово, чтобы добавить, тапни ✕, чтобы убрать. onChange(tags) вызывается на каждое изменение; h:tags() читает их, h:add(s) / h:clear() меняют.

A single line that auto-scrolls horizontally when the text is longer than the screen. Handy for tickers and long status lines.

Одна строка, автоматически прокручивающаяся по горизонтали, когда текст длиннее экрана. Удобно для бегущих строк и длинных статусов.

A pie or donut chart from weighted segments; colours default to a rotating palette. h:set(segments) redraws it. Good for breakdowns (storage, spend, votes).

Круговая или пончиковая диаграмма из взвешенных сегментов; цвета по умолчанию берутся из ротации палитры. h:set(segments) перерисует. Хорошо для разбивок (память, траты, голоса).

A row of tappable colour swatches (theme roles, tones or #hex); the selected one gets a ring. onChange(hex) fires on pick; h:get() → "#RRGGBB", h:name() → the chosen token. Let users theme your plugin.

Ряд кликабельных образцов цвета (роли темы, тоны или #hex); у выбранного появляется обводка. onChange(hex) вызывается при выборе; h:get() → "#RRGGBB", h:name() → выбранный токен. Дай пользователю темизировать твой плагин.

Overlapping circular avatars with initials and a +N overflow chip. Handy for members, participants and assignees.

Перекрывающиеся круглые аватары с инициалами и чипом +N для остатка. Удобно для участников, членов и исполнителей.

A QR code for any text — a link, Wi-Fi credentials, a contact, a payment string. h:set(text) re-encodes it. Generated on-device, works offline.

QR-код для любого текста — ссылка, данные Wi-Fi, контакт, платёжная строка. h:set(text) перекодирует. Генерируется на устройстве, работает оффлайн.

More styling on any widget. Colors accept #hex, theme roles (primary, error, surface, onSurface, muted, secondaryContainer …) and tones (success, warning, danger, info, purple, cyan …).

Больше стилей у любого виджета. Цвета: #hex, роли темы (primary, error, surface, onSurface, muted, secondaryContainer …) и тона (success, warning, danger, info, purple, cyan …).

ui:card(f):gradient("#312E81", "#0EA5E9", "diagonal"):border(1, "outline")

Built-in animations for feedback (shake an invalid field, pulse a stat that changed, fade rows in).

Встроенные анимации для отклика (потрясти невалидное поле, пульснуть изменившийся показатель, плавно показать строки).

if not ok then host:shake():error("Unreachable") end

Interaction and text extras available on every handle.

Взаимодействие и текстовые дополнения у каждого хендла.

row:onLongClick(function() ui:menu({ "Copy", "Delete" }, act) end)

Reactive text: the widget re-renders whenever Wex.state.set(key, v) changes the key. Inputs, switches and checkboxes bind two-way. Stats bind their value.

Реактивный текст: виджет перерисовывается при каждом Wex.state.set(key, v). Поля ввода, переключатели и чекбоксы привязываются в обе стороны. Stat привязывает значение.

ui:kv("Status", ""):bind("status")
ui:stat("Packets", "0"):bind("packets", function(n) return Wex.format.number(n) end)
Wex.state.set("status", "online")

Text-field handle methods. :onSubmit fires on the keyboard's Done/Search/Enter.

Методы хендла поля ввода. :onSubmit срабатывает по Done/Search/Enter на клавиатуре.

local q = ui:input("Host"):icon("search"):clearButton():onSubmit(lookup)

Button styles at creation ("filled" | "outlined" | "text" | "tonal" | "danger" | "success") or later via the handle. :loading(true) disables and shows "…". :text(s) changes the label after creation; :onClick(fn) receives the handle as its argument. There is no :set on a button.

Стили кнопки при создании ("filled" | "outlined" | "text" | "tonal" | "danger" | "success") или позже через хендл. :loading(true) блокирует и показывает "…". :text(s) меняет подпись после создания; :onClick(fn) получает хендл аргументом. Метода :set у кнопки нет.

local b = ui:button("Scan", scan, "tonal"):icon("wifi")
b:loading(true); … b:loading(false)

Selection handles — read or drive the control from code. :get() returns the 1-based index (or an index array for multiChips). :set() invokes the callback on segmented and radio, and :set()/:toggle() on switch and checkbox; chips, dropdown and stepper stay silent — see «Callbacks fire during creation».

Хендлы выбора — читайте или управляйте контролом из кода. :get() возвращает индекс с 1 (или массив индексов для multiChips). :set() вызывает колбэк у segmented и radio, а :set()/:toggle() — у switch и checkbox; chips, dropdown и stepper молчат — см. «Callbacks fire during creation».

local mode = ui:dropdown("Mode", modes, nil, 1)
print(mode:label())

Containers can be emptied and re-filled without touching the rest of the screen; lists re-render rows from changed data.

Контейнеры можно очищать и наполнять заново, не трогая остальной экран; списки перерисовывают строки по изменившимся данным.

local box = ui:card(function(c) c:text("loading…") end)
Wex.http(u, function(r) box:rebuild(function(c) render(c, r.json) end) end)

Image sources: http(s) (needs "network"), data:…;base64, or a Wex.files / Wex.download file name. Progress can switch between determinate and indeterminate.

Источники картинок: http(s) (нужен "network"), data:…;base64 или имя файла из Wex.files / Wex.download. Прогресс переключается между определённым и неопределённым.

Wex.download(u, "pic.jpg", function(ok) if ok then img:set("pic.jpg") end end)

Entrances and attention cues on any widget: continuous :spin (stop with :stopSpin), a :bounce, a 3D :flip, :zoomIn / :dropIn reveals, and :highlight to flash a colour over it and fade out — all non-destructive to the widget’s own background.

Появления и акценты на любом виджете: непрерывный :spin (останавливается :stopSpin), :bounce, 3D-:flip, появления :zoomIn / :dropIn и :highlight — вспышка цветом поверх с угасанием. Ничего не портит из собственного фона виджета.

Animated text on any text handle: :countTo rolls the number up (with grouping and optional prefix/suffix), :typewriter reveals a string character by character. Great for stats and reveals.

Анимация текста на любом текстовом хендле: :countTo прокручивает число вверх (с разрядами и необязательным префиксом/суффиксом), :typewriter печатает строку по буквам. Хорошо для показателей и эффектных выводов.

Height reveals and list choreography: :expand / :collapse animate a view’s height open/closed; :stagger fades a container’s children in one after another for a lively list.

Раскрытие по высоте и хореография списков: :expand / :collapse анимируют высоту вью открыто/закрыто; :stagger по очереди проявляет детей контейнера, оживляя список.

Expressive motion on any handle. :spring drives properties to their targets with a real damped spring (physics, not a fixed tween): scale, x / y (dp translation), rotate (degrees), alpha; tune stiffness (20–1500, ~380) and damping (ratio 0.1–2, ~0.72). :shape sets an expressive corner shape and :shapeMorph animates to it — tokens pill, square, cookie, soft, xl, lg, md, sm (or a dp number).

Выразительное движение на любом хендле. :spring гонит свойства к целям настоящей пружиной с затуханием (физика, не фиксированный твин): scale, x / y (сдвиг в dp), rotate (градусы), alpha; настраивай stiffness (20–1500, ~380) и damping (коэффициент 0.1–2, ~0.72). :shape задаёт выразительную форму углов, а :shapeMorph анимирует к ней — токены pill, square, cookie, soft, xl, lg, md, sm (или число dp).

local box = ui:card(function(c) c:text("Springy") end)
ui:button("Bounce", function()
  box:spring({ y = -18, stiffness = 600, damping = 0.55 })
  box:shapeMorph("pill", 280)
end)

:glass makes a card or surface a frosted translucent panel (Expressive chrome). :blur blurs the view's own content (Android 12+). :shared(name) marks a view as a shared element — the next ui:push flies a same-named view on the new screen out from where this one sits (container transform).

:glass делает карточку или поверхность матовой полупрозрачной панелью (выразительный chrome). :blur размывает собственное содержимое вью (Android 12+). :shared(name) помечает вью как общий элемент — следующий ui:push вылетает одноимённым вью нового экрана из места, где стоит этот (container transform).

-- screen A
ui:avatar("me.jpg", 56):shared("hero")

-- inside the ui:push build (screen B)
ui:avatar("me.jpg", 120):shared("hero")   -- morphs out from A

Delight and feedback: ui:confetti drops a burst of colour over the whole screen (a win, a completed task); ui:haptic fires a short vibration through the device’s haptics — no permission needed.

Радость и отклик: ui:confetti сыпет всплеск конфетти на весь экран (победа, завершённая задача); ui:haptic даёт короткую вибрацию через haptics устройства — разрешений не нужно.

Gestures on ordinary widgets, not just ui:canvas. :onSwipe reports a direction ("left"/"right"/"up"/"down"); :swipeToDismiss drags the widget with the finger and, past ~38% of its width, animates it out and calls back — swipe-to-delete for list rows; :draggable moves a widget freely and reports where it was dropped in dp; :offset nudges any widget without touching layout. Each keeps :onClick working and only claims the touch stream once a real drag starts, so the surrounding scroll still behaves.

Жесты у обычных виджетов, а не только у ui:canvas. :onSwipe сообщает направление ("left"/"right"/"up"/"down"); :swipeToDismiss тянет виджет за пальцем и после ~38% ширины улетает и вызывает колбэк — свайп-удаление строк списка; :draggable свободно перетаскивает виджет и сообщает точку броска в dp; :offset смещает любой виджет, не трогая разметку. Всё это не ломает :onClick и перехватывает касания только когда началось настоящее перетаскивание, поэтому окружающая прокрутка работает как прежде.

Request options: json = table sends JSON (Content-Type set, method defaults to POST); form = { k = v } sends urlencoded; binary = true returns base64 body; save = "name" streams to the sandbox file; auth = { user, pass } (Basic) or "token" (Bearer); timeout in ms.

Опции запроса: json = таблица шлёт JSON (Content-Type выставляется, метод по умолчанию POST); form = { k = v } — urlencoded; binary = true возвращает body в base64; save = "name" пишет в файл песочницы; auth = { user, pass } (Basic) или "token" (Bearer); timeout в мс.

returnsвозвращаетres = { ok, status, body, json (auto-decoded when JSON), headers = { lowercased }, contentType, url (final), ms, size, error, file }.res = { ok, status, body, json (декодируется автоматически), headers = { в нижнем регистре }, contentType, url (финальный), ms, size, error, file }.

Wex.http({ url = api .. "/login", json = { user = u, pass = p }, timeout = 8000 }, function(r)
  if r.ok then token = r.json.token else ui:toast(r.error) end
end)

Shorthands. A table body is sent as JSON automatically.

Сокращения. Табличное тело отправляется как JSON автоматически.

Wex.http.json(api .. "/items", { name = n }, function(r) print(r.status) end)

ws:send(text | table→JSON) / ws:sendJson(t) / ws:close() / ws:isOpen(). Binary frames arrive as (utf8, base64).

ws:send(text | таблица→JSON) / ws:sendJson(t) / ws:close() / ws:isOpen(). Бинарные кадры приходят как (utf8, base64).

Raw TCP client for custom protocols (telnet, redis, SMTP banners…). s:send(text) / s:sendLine(text) / s:sendBase64(b64) / s:close() / s:isOpen(). Data arrives in chunks on the main thread.

Сырой TCP-клиент для своих протоколов (telnet, redis, баннеры SMTP…). s:send(text) / s:sendLine(text) / s:sendBase64(b64) / s:close() / s:isOpen(). Данные приходят чанками в главном потоке.

local s = Wex.tcp.connect(host, 6379, {
  onConnect = function(s) s:sendLine("PING") end,
  onData = function(d) term:append(d) end })

Fire a datagram (optionally wait for one reply); listen on a port (l:close(), l:send(host, port, data), l.port).

Отправить датаграмму (опционально дождаться одного ответа); слушать порт (l:close(), l:send(host, port, data), l.port).

Wex.udp.send("255.255.255.255", 9, "wake")

Resolve names, reverse-lookup, latency probe (ICMP/echo, falling back to a TCP knock on 443/80), single-port check.

Резолв имён, обратный резолв, замер задержки (ICMP/echo с фолбэком на TCP 443/80), проверка одного порта.

Wex.net.ping("1.1.1.1", 1500, function(ms) rtt:set(ms and (ms .. " ms") or "—") end)

Parallel TCP port check, capped at 512 ports per call (default list of common ports when omitted).

Параллельная проверка TCP-портов, до 512 портов за вызов (без списка — распространённые порты).

Wex.net.ports(ip, { from = 1, to = 512 }, 300, function(open) term:ok(table.concat(open, ", ")) end,
  function(d, t) prog:set(d * 100 / t) end)

Local addressing and connectivity info — no permission needed. type() → wifi | cellular | ethernet | vpn | bluetooth | none.

Локальная адресация и состояние сети — без разрешений. type() → wifi | cellular | ethernet | vpn | bluetooth | none.

local r = Wex.net.cidrRange("192.168.1.0/24")
print(r.first, r.last, r.count)

Download streams into the sandbox file `name` (no size limit in memory); upload is multipart/form-data with optional headers.

Download пишет поток в файл песочницы `name` (без лимита в памяти); upload — multipart/form-data с необязательными заголовками.

Streamed download with progress and cancellation — pass a table instead of a callback (needs the network permission). onProgress(done, total) reports bytes (total is -1 when the length is unknown); onDone(res) gets { ok = true, path, name } or an error result ({ ok = false, error }, error = "cancelled" when you call handle:cancel()). The file lands in the Wex.files sandbox and a cancelled/failed transfer leaves no partial file. The legacy download(url, name, fn(ok, res)) is unchanged.

Загрузка потоком с прогрессом и отменой — передай таблицу вместо колбэка (нужно разрешение network). onProgress(done, total) отдаёт байты (total = -1, если длина неизвестна); onDone(res) получает { ok = true, path, name } либо ошибку ({ ok = false, error }, error = "cancelled" при handle:cancel()). Файл ложится в песочницу Wex.files, а отменённая/упавшая загрузка не оставляет частичного файла. Старый download(url, name, fn(ok, res)) не изменился.

local dl = Wex.download("https://example.com/big.zip", "big.zip", {
  onProgress = function(done, total) bar:set(done, total) end,
  onDone = function(res) if res.ok then Wex.toast("saved " .. res.path) end end,
})
-- dl:cancel()

Typed helpers over the same key/value store; set(k, table) stores JSON automatically; get(k, default) returns the default when missing.

Типизированные хелперы над тем же хранилищем; set(k, таблица) сохраняет JSON; get(k, default) возвращает default, если ключа нет.

local n = Wex.storage.increment("runs")
Wex.storage.setJson("hosts", hosts)

Schema versioning for saved data. version() reads the stored schema number (0 if never set). migrate(to, fn) runs fn(currentVersion) once when the stored version is below to, then records to — call it before the first read (in build or Plugin.onUpdate) so old data is reshaped exactly once.

Версионирование схемы сохранённых данных. version() читает номер схемы (0, если не задан). migrate(to, fn) один раз вызывает fn(текущаяВерсия), когда сохранённая версия меньше to, и записывает to — вызывайте до первого чтения (в build или Plugin.onUpdate), чтобы старые данные переформатировались ровно один раз.

Wex.storage.migrate(2, function(from)
  local single = Wex.storage.get("host")
  if single then Wex.storage.setJson("hosts", { single }) end
end)

Key/value with expiry — ideal for API responses. remember() returns the cached value or computes, stores and returns fn()'s result.

Ключ/значение с истечением — идеально для ответов API. remember() возвращает кэш или вычисляет, сохраняет и возвращает результат fn().

local geo = Wex.cache.remember("geo:" .. ip, 3600, function() return lookup(ip) end)

More sandbox file operations. info() lists { name, size, modified }; path()/dir() give absolute paths (e.g. for ui:image or audio.play).

Больше операций с файлами песочницы. info() — список { name, size, modified }; path()/dir() дают абсолютные пути (для ui:image или audio.play).

Wex.files.append("log.txt", os.time() .. " ok\n")

Binary files via base64, JSON round-trips, SHA-256 of a file, and handing a file to another app (share sheet / viewer).

Бинарные файлы через base64, JSON туда-обратно, SHA-256 файла и передача файла другому приложению (шаринг / просмотр).

Wex.files.writeJson("report.json", report)
Wex.files.share("report.json", "application/json")

Typed SQLite helpers: rows() returns numbers as numbers and NULL as nil (query() keeps the legacy all-strings shape). insert/update/delete build the SQL for you.

Типизированные хелперы SQLite: rows() возвращает числа числами, NULL как nil (query() сохраняет старый формат «всё строки»). insert/update/delete собирают SQL сами.

local id = db:insert("hosts", { ip = ip, rtt = ms })
local row = db:one("SELECT * FROM hosts WHERE id = ?", { id })

Schema introspection, batched writes in a transaction (rolled back if fn errors), database file management.

Интроспекция схемы, пакетная запись в транзакции (откатывается при ошибке fn), управление файлами БД.

db:transaction(function(d) for _, h in ipairs(hosts) do d:insert("hosts", h) end end)

Reactive SQLite. db:live re-runs its query and calls fn(rows) after every write (and once immediately), so a table can drive ui:view directly; db:onChange fires after a write to a given table (or any). Each returns a { stop() } handle. Callbacks run synchronously on the writing thread; writes inside a db:transaction fire a single coalesced notification after commit (never intermediate rows), and a callback that itself writes is coalesced rather than recursing. Keep live queries selective — every write re-runs them all.

Реактивный SQLite. db:live перезапускает свой запрос и зовёт fn(rows) после каждой записи (и один раз сразу), поэтому таблица может напрямую питать ui:view; db:onChange срабатывает после записи в указанную таблицу (или в любую). Каждый возвращает хендл { stop() }. Колбэки идут синхронно на потоке записи; записи внутри db:transaction дают одно объединённое уведомление после коммита (без промежуточных строк), а колбэк, который сам пишет, объединяется, а не рекурсирует. Держи live-запросы избирательными — каждая запись перезапускает их все.

local sub = db:live("SELECT * FROM todo ORDER BY done, id", function(rows)
  listView:rebuild(function(c)
    for _, r in ipairs(rows) do c:item({ title = r.title }) end
  end)
end)
db:insert("todo", { title = "Buy milk", done = 0 })   -- the live query re-fires
-- sub:stop() to unsubscribe

Keystore-encrypted storage; set() now reports success.

Хранилище, шифруемое Keystore; set() теперь сообщает об успехе.

Pretty printing, safe deep access by path (nil/default instead of an error), shallow merge and table introspection.

Красивая печать, безопасный доступ по пути (nil/default вместо ошибки), поверхностное слияние и интроспекция таблиц.

local city = Wex.json.get(res.json, "location.city", "?")

String helpers Lua lacks. template() fills ${name} / {{name}} from a table.

Строковые хелперы, которых нет в Lua. template() подставляет ${name} / {{name}} из таблицы.

ui:text(Wex.str.template("Hello, ${name}!", { name = user }))
for _, p in ipairs(Wex.str.split("a, b,,c", ",", true)) do … end

URL parsing and building with proper encoding.

Разбор и сборка URL с корректным кодированием.

local u = Wex.url.build(api .. "/search", { q = query, limit = 20 })

Real (Java) regular expressions — groups, lookarounds, flags "i" (ignore case), "m" (multiline), "s" (dot matches newline).

Настоящие (Java) регулярные выражения — группы, lookaround, флаги "i" (без регистра), "m" (многострочно), "s" (точка ловит перевод строки).

for _, m in ipairs(Wex.regex.matchAll(log, "(\\d+\\.\\d+\\.\\d+\\.\\d+)")) do ips[#ips+1] = m[1] end

Human-readable formatting localized to the device language ("1.5 MB", "2h 03m", "5 min ago", "01:42").

Человекочитаемое форматирование с учётом языка устройства («1.5 MB», «2ч 03м», «5 мин назад», «01:42»).

ui:kv("Downloaded", Wex.format.bytes(total) .. " · " .. Wex.format.speed(rate))

Cryptographically seeded randomness. int(a, b) includes both ends. shuffle returns a new table and leaves the argument untouched; pick returns nil for an empty table.

Криптографически инициализированная случайность. int(a, b) включает обе границы. shuffle возвращает новую таблицу и не трогает аргумент; pick возвращает nil для пустой таблицы.

local pass = Wex.random.string(16)

Numeric helpers over arrays and coordinates (geoDistance in meters).

Числовые хелперы над массивами и координатами (geoDistance в метрах).

ui:kv("Avg RTT", Wex.math.round(Wex.math.avg(samples), 1) .. " ms")

Color math for charts and custom styling. heat() maps 0..1 to green → yellow → red — great for latency / load.

Цветовая математика для графиков и стилей. heat() отображает 0..1 в зелёный → жёлтый → красный — удобно для задержки / нагрузки.

rtt:color(Wex.color.heat(ms / 300))

CSV with quotes (header = true yields { col = value } rows), a plain XML tree, and gzip via base64.

CSV с кавычками (header = true даёт строки { col = value }), простое XML-дерево и gzip через base64.

local rows = Wex.csv.parse(Wex.files.read("hosts.csv"), ",", true)
for _, r in ipairs(rows) do print(r.ip) end

More date/time helpers (os.date is unavailable in the sandbox).

Больше хелперов даты/времени (os.date в песочнице недоступен).

local tomorrow = Wex.time.add(Wex.time.startOfDay(), { days = 1 })

Authenticator-grade TOTP/HOTP, key derivation, extra digests and base64 variants.

TOTP/HOTP уровня аутентификатора, вывод ключей, дополнительные дайджесты и варианты base64.

local t = Wex.crypto.totp(Wex.secure.get("otp_secret"))
code:set(t.code); left:set(t.remaining .. "s")

In-plugin event bus — decouple screens, timers and network callbacks. emit() returns the number of listeners called.

Шина событий внутри плагина — развязывает экраны, таймеры и сетевые колбэки. emit() возвращает число вызванных слушателей.

Wex.events.on("host:found", function(ip) list:count(#hosts) end)
Wex.events.emit("host:found", ip)

Reactive state shared with widget handles' :bind(key). persist()/restore() mirror a key into Wex.storage.

Реактивное состояние, общее с :bind(key) у хендлов. persist()/restore() зеркалят ключ в Wex.storage.