Skip to content
alfowler1976 edited this page Oct 30, 2026 · 5 revisions

API Reference

browser_io.is_supported()

Returns whether this is an HTML5 build.

local supported = browser_io.is_supported()

Returns

boolean

true on HTML5 builds and false on other build targets.

This does not test an individual browser API. Use the can_*() functions for feature detection.


browser_io.can_copy()

Returns whether the current browser context exposes clipboard text writing.

local supported = browser_io.can_copy()

The implementation requires:

  • a secure browser context
  • navigator.clipboard
  • navigator.clipboard.writeText

A returned value of true means the operation can be attempted. Browser security policy can still reject the request.


browser_io.can_paste()

Returns whether the current browser context exposes clipboard text reading.

local supported = browser_io.can_paste()

The implementation requires:

  • a secure browser context
  • navigator.clipboard
  • navigator.clipboard.readText

A returned value of true does not guarantee permission to read the clipboard.


browser_io.can_open_file()

Returns whether the browser exposes the APIs required by open_file().

local supported = browser_io.can_open_file()

The current implementation checks for DOM element creation and FileReader.


browser_io.can_save_file()

Returns whether the browser exposes the APIs required by save_file().

local supported = browser_io.can_save_file()

The current implementation checks for:

  • Blob
  • URL.createObjectURL
  • an <a> element with download support

browser_io.can_drop_files()

Returns whether the browser exposes drag/drop and file-reading APIs.

local supported = browser_io.can_drop_files()

This is an API capability check only. It does not guarantee that an external file-drag workflow is practical on a touch-only device.


browser_io.copy(text, callback)

Copies UTF-8 text to the system clipboard.

Signature

local request_id = browser_io.copy(text, callback)

Parameters

text

: Lua string containing the text to copy.

callback

: Function called as:

callback(self, result)

Result

On success:

{
    success = true,
    cancelled = false,
    operation = "copy"
}

On failure:

{
    success = false,
    cancelled = false,
    operation = "copy",
    error = "..."
}

Returns

A numeric request ID.

Example:

local function copy_callback(self, result)

	if result.success then
		pprint("data copied")
	else
		pprint("Clipboard copy failed: "..result.error)
	end
end

function copy(data)
	browser_io.copy(data, copy_callback)
end

browser_io.paste(callback)

Reads UTF-8 text from the system clipboard.

Signature

local request_id = browser_io.paste(callback)

Parameters

callback

: Function called as:

callback(self, result)

Successful result

{
    success = true,
    cancelled = false,
    operation = "paste",
    data = "...",
    size = 123
}

size is the byte length of the Lua string.

An empty successful paste returns:

data = ""
size = 0

Returns

A numeric request ID.

Example:

local function paste_callback(self, result)

	if result.success then
		print("PASTED:", result.data)
	else
		pprint("Clipboard paste failed")
	end
end

function paste()
	browser_io.paste(paste_callback)
end

browser_io.open_file(options, callback)

Opens a browser file picker and reads one selected file into a Lua string.

Supported forms

browser_io.open_file(nil, callback)
browser_io.open_file(options, callback)

callback

: Function called as:

callback(self, result)

Options

{
    accept = ".ohm",
    max_size = 16384
}

accept

Optional HTML-style accept filter.

The JavaScript bridge supports:

  • file extensions such as .txt
  • exact MIME types such as application/json
  • wildcard MIME types such as image/*
  • comma-separated combinations

Example:

accept = ".txt,.json,application/json"

The default is an empty string, which does not restrict file type.

The selected file is checked against the accept rules by the extension after selection as well as being supplied to the browser file input.

max_size

Maximum file size in bytes.

Default:

16 MiB

A supplied numeric value is used only when greater than zero.

Successful result

{
    success = true,
    cancelled = false,
    operation = "open_file",
    name = "level.ohm",
    data = "...",
    size = 2048
}

The file data is binary-safe.

A zero-byte file returns:

data = ""
size = 0

Cancellation

If the browser reports that the file picker was cancelled:

result.cancelled == true

Returns

A numeric request ID.

Example:

local function open_callback(self, result)

	if result.success then
		print("data:", result.data)
	else
		pprint("Open failed:", result.error)
	end
end

function open_file()
	browser_io.open_file( {accept = ".ohm", max_size = 16 * 1024}, open_callback)
end

browser_io.save_file(filename, data, options, callback)

Creates a browser download from a Lua string.

Supported forms

browser_io.save_file(filename, data, nil, callback)
browser_io.save_file(filename, data, options, callback)

Parameters

filename

: Suggested download filename.

data

: Lua string containing the file bytes. Binary data is supported.

options

: Optional table.

callback

: Function called as:

callback(self, result)

Options

{
    mime_type = "text/plain;charset=utf-8"
}

Default MIME type:

application/octet-stream

Successful result

{
    success = true,
    cancelled = false,
    operation = "save_file"
}

A successful result means the extension created the Blob, triggered the browser download link, and handed the operation to the browser. The extension cannot confirm that the user eventually saved the file to disk.

Returns

A numeric request ID.

Example:

local function save_callback(self, result)

	if result.success then
		print("success")
	else
		pprint("failed")
	end
end

function save_file()
	local text = "hello world!"
	
	browser_io.save_file("hello.txt",text,{mime_type = "text/plain;charset=utf-8"},save_callback)
end

browser_io.set_drop_listener(options, callback)

Registers a persistent drag-and-drop file listener.

The listener is installed on the browser window in capture mode so that handled file drops can suppress the browser's normal navigation behaviour.

Supported forms

browser_io.set_drop_listener(nil, callback)
browser_io.set_drop_listener(options, callback)

callback

: Function called as:

callback(self, result)

Options

The options are the same as open_file():

{
    accept = ".txt",
    max_size = 16384
}

Default max_size is 16 MiB.

Successful drop result

{
    success = true,
    cancelled = false,
    operation = "drop_file",
    name = "level.ohm",
    data = "...",
    size = 2048
}

Only the first file in a drop operation is processed.

The listener remains active after a callback and can receive additional drop events.

Calling set_drop_listener() again replaces the previous Lua listener.

Returns

true when enabled on HTML5.

Returns false on unsupported build targets.

Example:

local function drop_callback(self, result)

	if result.success then
		print("success",result.data)
	else
		pprint("failed: "..result.error)
	end
end

function drop_listener()
	browser_io.set_drop_listener({accept = ".ohm",max_size = 16384}, drop_callback)
end

browser_io.cancel_drop_listener()

Removes the persistent drag-and-drop listener and releases its Lua callback.

browser_io.cancel_drop_listener()

It is good practice to call this from final() when leaving a screen that enabled drag and drop:

function final(self)
    browser_io.cancel_drop_listener()
end

No value is returned.