Lua API

Trusted Lua API

Viset capture files are trusted, unsandboxed Lua 5.2 programs. Standard Lua libraries are open, local modules may be loaded from the capture directory, and the API may start processes or make network requests. Do not run an untrusted capture.

Each expanded output gets a fresh Lua state and browser session.

Context

• viset.api_version is 1.
• viset.script.directory is the absolute capture directory.
• viset.context.script_path and viset.context.output are absolute paths.
• viset.context.device contains the selected device.
• viset.context.axes contains the current matrix values.
• viset.context.data contains the TOML [data] table.

Durations are positive millisecond numbers or strings such as "250ms" and "1.5s".

Page

• viset.page.navigate(url) navigates to an absolute URL.
• viset.page.evaluate(script, arguments?) evaluates JavaScript and returns a JSON-shaped Lua value. With arguments, the script evaluates to a function.
• viset.page.wait_for(expression, timeout) polls until JavaScript returns Boolean true.
• viset.page.animate(options) runs a synchronous requestAnimationFrame update function with progress and timing state.
• viset.javascript(source) returns its string unchanged as an identity marker; it does not execute or validate JavaScript.

Capture

For PNG output:

viset.page.navigate("https://example.com")
viset.snapshot()

For WebP output:

local recording = viset.record()
recording:start()
recording:during("500ms", function()
  viset.page.animate({
    duration = "400ms",
    easing = "in_out_sine",
    update = "({ progress }) => window.scrollTo(0, progress * 600)",
  })
end)
recording:stop()

start() begins or resumes visible recording. stop() pauses it. Repeated visible segments concatenate. during(duration, callback?) runs the optional callback and guarantees the requested minimum visible duration. viset.sleep(duration) waits without changing recording visibility.

HTTP and processes

• viset.http.get(options) performs one GET and returns status, headers, and body.
• viset.http.wait(options) retries until a 2xx response or timeout.
• viset.process.start(options) starts a child and returns an integer handle.
• viset.process.wait(handle, timeout?) waits for normal exit.
• viset.process.stop(handle) stops the process tree and returns exit_code, stdout, and stderr.

Viset attempts to stop every active managed child when capture completes or fails.

Emulation

viset.emulation.apply(device) applies a device-shaped table. viset.emulation.touch(x, y) dispatches one touch at viewport coordinates. The selected context device is already active when the script starts.

See the repository's generated LuaCATS metadata for exact table shapes.