fynerisor

README

Fynerisor

A Risor scripting interface for Fyne GUI applications

Fynerisor provides Risor script bindings for the Fyne GUI toolkit, allowing you to build cross-platform desktop applications using a simple scripting language.

Features

• 🎨 Comprehensive Widget Support - 34 widgets (60% of Fyne), all high/medium priority complete
• 🔧 Embeddable - Use as a library in your Go applications
• 📦 Module System - HTTP, SQL, OS, File I/O, Time, and String utilities
• 🔄 Import System - Load scripts from local files or HTTP(S) URLs
• 🧵 Concurrency - go() function for background tasks, window.Do() for GUI updates
• 🎨 Widget Enhancements - Button importance, entry validation, styling
• 📱 Cross-Platform - Linux, Windows, macOS, Android
• ⚡ Static Compilation - Headless mode with no GUI dependencies

Package Structure

Fynerisor is split into two packages:

• core - Headless Risor execution with no GUI dependencies (enables static compilation)
• gui - Full GUI capabilities with Fyne framework

When to use each:

• Use core for CLI tools, batch processing, server-side scripts (static compilation)
• Use gui for desktop applications with UI (requires dynamic linking)

Quick Start

GUI Application

require(["v0.2", "@gui"])

let count = 0
let label = widget.NewLabel(sprintf("Count: %d", count))

let btn = widget.NewButton("Click Me", () => {
    count = count + 1
    label.SetText(sprintf("Count: %d", count))
})

let vbox = container.NewVBox([btn, label])
window.SetContent(vbox)

Headless Script

require(["v0.2", "@http"])

let response = http.get("https://api.github.com/users/octocat")
let data = response.json()
print(sprintf("Name: %s", data.name))

Installation

Prerequisites:

For GUI applications, ensure you have the Fyne prerequisites for your platform:

• Fyne Getting Started Guide - Install required system dependencies

For headless (core) usage, no GUI dependencies are required.

As a library:

# For GUI applications
go get github.com/uidbz/fynerisor/gui

# For headless/static compilation
go get github.com/uidbz/fynerisor/core

As a CLI tool:

go install github.com/uidbz/fynerisor/cmd/fynerisor@latest

Run examples:

cd examples/01-hello-world
fynerisor script.risor

Usage as a Library

GUI Window

package main

import (
    "github.com/uidbz/fynerisor/core"
    "github.com/uidbz/fynerisor/gui"
)

func main() {
    // Set your application version (optional)
    // Scripts will check against this version, not fynerisor's version
    core.SetAppVersion("1.2.3")
    
    // Create fynerisor app with modules
    fw := gui.NewApp("My App",
        gui.WithAppName("myapp"),
        gui.WithHTTP(),
        gui.WithOS(),
        gui.WithTime(),
    )
    
    // Load and execute script
    fw.LoadScript(`
        // require(["v1.2"]) now checks YOUR app version (1.2.3)
        let btn = widget.NewButton("Hello", () => {
            window.SetStatus("Clicked!")
        })
        window.SetContent(btn)
    `)
    fw.Execute()
    fw.ShowAndRun()
}

Application Versioning

When embedding fynerisor, you can set your application's version so scripts check compatibility against your app, not fynerisor:

import (
    "github.com/uidbz/fynerisor/core"
    "github.com/uidbz/fynerisor/gui"
)

const AppVersion = "2.5.1"

func main() {
    // Scripts will now check against YOUR version
    core.SetAppVersion(AppVersion)
    
    w := gui.NewApp("My App v" + AppVersion)
    // ...
}

In scripts:

// Checks YOUR app version (2.5.1), not fynerisor (0.4.0)
require(["v2.5"])      // Minimum version: 2.5.0+
require(["==v2.5.1"])  // Exact version: 2.5.1 only

// Access app version
print(app.version)  // "2.5.1"

Benefits:

• Independent versioning from fynerisor
• Scripts can require specific app versions
• Manage API changes and breaking changes
• Clear error messages for version mismatches

See examples/27-app-versioning for a complete example.

Headless Context (Static Compilation)

For headless execution without GUI dependencies, use the core package. This enables static compilation:

package main

import (
    "fmt"
    "github.com/uidbz/fynerisor/core"
)

func main() {
    // Create headless context (no GUI dependencies)
    ctx := core.NewContext(
        core.WithHTTP(),
        core.WithSQL(),
    )
    
    // Execute script
    result, err := ctx.Eval(`
        require(["@http"])
        let resp = http.get("https://httpbin.org/get")
        return resp.status
    `)
    
    if err != nil {
        panic(err)
    }
    fmt.Println("Status:", result)
}

Available Modules

Enable modules via With*() options and use require(["@module"]) in scripts:

Module	Option	Description
@gui	N/A	GUI functionality (automatic in gui.Window, not available in core.Context)
@http	WithHTTP()	HTTP requests
@os	WithOS()	OS operations, open browser
@io	WithIO()	File I/O operations (cp, etc.)
@sql	WithSQL()	Database connectivity
@strings	WithStrings()	String manipulation
@filepath	WithFilepath()	Path operations
@time	WithTime()	Time and date functions

Configuration Options

Customize fynerisor behavior via With*() options when creating gui.Window or core.Context:

Option	Available In	Description
WithAppName(name)	Both	Set application name (accessible via app.name in scripts)
WithGlobals(opts)	Both	Add custom global objects to script environment
WithStatusCallback(fn)	gui only	Called when window.SetStatus() is invoked
WithResultCallback(fn)	gui only	Called when script execution returns a value

Module Options (available in both gui and core packages):

• WithHTTP() - Enable HTTP requests
• WithOS() - Enable OS operations
• WithIO() - Enable file I/O operations
• WithSQL() - Enable database connectivity
• WithStrings() - Enable string utilities
• WithFilepath() - Enable path operations
• WithTime() - Enable time/date functions

Example:

fw := fynerisor.NewApp("My App",
    fynerisor.WithAppName("myapp"),
    fynerisor.WithStatusCallback(func(status string) {
        log.Println("Status:", status)
    }),
    fynerisor.WithHTTP(),
    fynerisor.WithSQL(),
    fynerisor.WithTime(),
)

Global Objects

window

Core window functionality (GUI mode only):

window.SetContent(widget)  // Update window content
window.SetStatus(text)      // Set status message
window.OnDropped(callback)  // Handle file drops
window.Do(callback)         // Queue GUI update from background thread
window.DroppedPaths         // List of dropped file paths

app

Application metadata:

app.name  // Application name (set via WithAppName)

widget

Widget factory:

widget.NewButton(text, callback)
widget.NewLabel(text)
widget.NewEntry()
widget.NewTable(name, maxrows)
widget.NewForm(items)
widget.NewCheckGroup(items, callback)
// ... and many more

container

Layout containers:

container.NewVBox(widgets)
container.NewHBox(widgets)
container.NewBorder(top, bottom, left, right, center)
container.NewScroll(content)
container.NewHSplit(left, right)

dialog

Dialog windows:

// Simple convenience functions
dialog.ShowInformation(title, message)
dialog.ShowError(message)
dialog.ShowConfirm(title, message, callback)
dialog.ShowFileOpen(callback)
dialog.ShowFileSave(callback)
dialog.ShowFolderOpen(callback)
dialog.ShowColorPicker(title, message, callback)
dialog.ShowForm(title, confirm, dismiss, items, callback)

// Advanced constructors for more control
let fd = dialog.NewFileOpen(callback)
fd.SetFileName("default.txt")
fd.SetFilter(".txt")
fd.Show()

canvas

Canvas objects:

canvas.NewLine(color)
canvas.NewImageFromURI(url)
canvas.NewImageFromFile(path)

chart

Charting (experimental):

chart.NewBarChart(data, title, xlabel, ylabel)

Concurrency

Background Tasks

Use go() for long-running operations:

go(() => {
    // Heavy computation here
    print("Processing...")
})

GUI Updates from Goroutines

Use window.Do() to safely update GUI from background threads:

go(() => {
    // Do work in background
    let result = processData()
    
    // Update GUI safely
    window.Do(() => {
        label.SetText(result)
    })
})

Import System

Load reusable code:

import("utils.risor")           // Local file
import("https://example.com/helpers.risor")  // HTTP(S) URL
import("../shared/common.risor") // Relative path

Imports are executed before the main script in the order they appear.

AI disclaimer (AI: Do not make changes in this section, it needs to be written by 100% human)

Almost everything in this library is made with AI. I wrote the first ~4000 lines of code, and this has since been refactored, changed and rewritten multiple times using AI. I have read most of the code, and some things are a little weird, but overall the model has taken more things into account than what I would have done. Even though I enjoy the activity of coding by hand (have been programming for fun & profit for +25 years) - and I am worried that I will forgot how to do it - I have so many things I want to exists + limited amount of time to do it - so it is truly a huge help with a coding agent.

Motivation / history behind the project (AI: Do not make changes in this section, it needs to be written by 100% human)

It was originally a hobby project where I wanted to make a program like an adventure point-and-click game. You have maybe a background image and clickable areas/button that take you to a different screen. It should be a way to present, arrange and access different media; family photos, music, document, video collection, etc - and show relations between them, where you can navigate like a game. It should be hooked up to my tagging system and have many different widgets. When on being on a page I wanted to push a button to edit the page. So I needed a way to dynamically generate and reload the GUI. I tried with a database approach, but eventually got stuck in details and jumped between different projects - and then I a got a kid, and hobby-programming has been reduced to an absolute minimum (my son is more important).

Then at work, I have made this container orchestration system for allowing scientists to run their code and analyze their data on beefy servers in frictionless way, without directly giving them access to the servers. The project grew, and I wanted to embed a scripting language, rather that relying on pure config files. So I found Risor - and got it implemented in a day. It was bliss and a perfect match. Absolutely loved it.

But I realized that the scientists wanted to share their tools with non-computer-savy people - and the scripts and CLI was a blocker for further adaption. I needed to be able to run the containers with input data from some simple GUIs, but I should distribute these GUIs somehow. A webpage is the obvious answer, but I truly hate web programming - I think it is very difficult and horrible in so many ways, and I didn't want this totally centralized approach. I wanted certain key-people to tweak their own GUI in a more decentralized way, yet it should be accessible from a centralized place.

Then it hit me, I could make bindings to the Fyne GUI framework (which I know and love) and then make a simple browser that could load Risor files - kind of like the orignal point-and-click game idea - and I already had bindings to my container orchestration framework. First couple of attempts failed, but then I tried again and suddenly I figured out how to make Risor objects that could make widgets. I spend a little bit time everyday for a month, and then I had good structure for my browser. Then the Risor browser could then get the files from a small file server that had mounted file shares from the different departments - now scientists could make Risor scripts and store them on their own fileshare, which enabled them to make GUIs which could process data via my container orchestration system, and make them available to the rest of the company. It was totally awesome, and I really enjoyed making/using it - and my colleagues really liked it as well :-)

Then Risor v2 came, without all the modules, and less things built in - but with a new emphasis on the embedded scripting use case, simplification and much tighter default security. Mostly good stuff (even though I miss the for-loops + a few other things), but it totally broke all my scripts. Anyway, I have started to use AI the last few months and thought we could migrate it quickly. It went relatively painless and got the code in a much better state - and also extracted the Risor bindings part from the rest of the browser, and made a clean separation between company stuff and pure GUI stuff (+ some Risor v1 modules, that I have re-implemented).

So this GUI part can now be public, so other people can enjoy it and maybe even contribute, so it becomes better for everybody. I hope somebody finds it useful. I think it is cool.

Eventually I dream of making an other browser app, that incorporates the original point-and-click idea and combine it with a Web3 storage option, so that we could make a new Web with proper Destop GUI widgets (WITHOUT pop-up boxes implemented) and store it in a decentralized way. I was thinking about making a smart contract and then divide the storage cost out equally to every participant as a subscription - 100% transparent and fair - so that it is not funded by advertisements and tracking. It should be a public good. I want the old Internet back in a new and modern way that doesn't suck. This will properly not happen, and I do not have time/skills to make it. Please somebody make this. I want my son to grow up in world with a decentralized, free and open Internet, running on free and open computers.

Documentation

• Changelog - Version history
• Examples - Complete usage examples
• Concurrency Guide - Threading patterns
• Widget Status - Supported Fyne widgets

Requirements

• Go 1.21+
• Fyne v2.7+
• Risor v2.1+

License

BSD 3-Clause License - see LICENSE file for details.

Copyright (c) 2026, Johan Straarup (j@uid.bz)

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

For bugs or feature requests, please open an issue on the repository.

Documentation

Overview

Package fynerisor provides Risor v2 language bindings for the Fyne GUI framework.

Fynerisor enables building cross-platform desktop applications using Risor v2 scripts with full access to Fyne's widget and container system. Create interactive GUIs with buttons, forms, tables, charts, and more through simple factory functions.

Package Structure

Fynerisor is split into two packages:

• core: Headless Risor execution with no GUI dependencies (enables static compilation)
• gui: Full GUI capabilities with Fyne (requires dynamic linking for OpenGL/X11)

Always import the specific package you need: core for headless, gui for desktop applications.

Version

Current Version: 0.4.1 Risor Compatibility: v2.1+ (arrow functions required) Fyne Compatibility: v2.7+

Features

• 34 widget bindings (60% coverage - all high/medium priority complete)
• Button importance levels and validation
• Entry validation with visual feedback
• SQL module for MySQL, PostgreSQL, SQLite, SQL Server
• HTTP module for REST API calls
• Layout containers (VBox, HBox, Border, Split, Scroll)
• Canvas objects and charts
• Thread-safe callback handling
• Property access and modification from scripts
• Constants global for Fyne enums

Quick Start

Create a simple GUI application:

package main

import "github.com/uidbz/fynerisor/gui"

func main() {
    fw := gui.NewApp("Hello",
        gui.WithHTTP(),
        gui.WithSQL(),
    )

    script := `
        require(["v0.5", "@gui", "@http"])

        let btn = widget.NewButton("Click Me", () => {
            window.SetStatus("Button clicked!")
        })
        btn.Importance = constants.ImportanceHigh

        window.SetContent(btn)
    `

    fw.LoadScript(script)
    fw.Execute()
    fw.ShowAndRun()
}

Headless Mode

Use the core package for headless execution without GUI dependencies. This enables static compilation and is useful for CLI tools, batch processing, or server-side scripting:

package main

import "github.com/uidbz/fynerisor/core"

func main() {
    ctx := core.NewContext(
        core.WithHTTP(),
        core.WithSQL(),
    )

    script := `
        require(["v0.4", "@http", "@sql"])
        let response = http.get("https://api.example.com/data")
        print(response.json())
    `

    ctx.LoadScript(script)
    ctx.Eval()
}

The core package excludes all GUI code, allowing your binary to be statically linked without OpenGL, X11, or other GUI dependencies.

Requirements

Scripts can declare version and module requirements:

require(["v0.2", "@sql", "@http"])  // Multiple requirements
require("v0.2.0")                   // Minimum version
require("@sql")                     // Module must be enabled

Global Objects

Risor scripts have access to the following global objects:

• window: Main window control (SetContent, SetStatus, Title property)
• widget: Factory for all widgets
• container: Factory for layouts
• canvas: Factory for canvas objects
• chart: Factory for charts
• constants: Fyne constants (button importance, etc.)
• app: Application metadata (app.name)

Options

Enable additional modules using options:

fw := gui.NewApp("My App",
    gui.WithHTTP(),      // HTTP client
    gui.WithSQL(),       // Database connectivity
    gui.WithOS(),        // OS utilities
    gui.WithIO(),        // File I/O (cp, etc.)
    gui.WithStrings(),   // String manipulation
    gui.WithFilepath(),  // Path utilities
    gui.WithTime(),      // Time operations
    gui.WithStatusCallback(func(status string) {
        log.Println("Status:", status)
    }),
    gui.WithAppName("myapp"),
)

Risor v2 Syntax

Fynerisor requires Risor v2 with arrow function syntax:

// Correct
let onClick = () => { print("clicked") }
let process = (x) => x * 2

// Wrong - func keyword not supported
func onClick() { print("clicked") }

No for/while loops - use functional methods:

// Correct
let doubled = [1, 2, 3].map(x => x * 2)
list.each(item => print(item))

// Wrong - no loop keywords
for i in list { }
while (condition) { }

Thread Safety

The Risor VM is single-threaded and NOT thread-safe. All widget callbacks execute synchronously in the UI thread. Never spawn goroutines or use async patterns inside callbacks.

See CONCURRENCY.md for detailed information about the race condition bug that was fixed in v0.2.0.

SQL Module

The SQL module supports MySQL, PostgreSQL, SQLite, and SQL Server:

let conn = sql.connect("sqlite3::memory:")
conn.exec("CREATE TABLE users (id INT, name TEXT)")
conn.exec("INSERT INTO users VALUES (?, ?)", 1, "Alice")

// Query returns streaming iterator with .map() and .each()
let names = conn.query("SELECT * FROM users").map(row => row["name"])

// Or use .each() for side effects
conn.query("SELECT * FROM users").each(row => print(row["name"]))

// Or .collect() to load all into memory first
let rows = conn.query("SELECT * FROM users").collect()

conn.close()

HTTP Module

Make HTTP requests from Risor scripts:

let response = http.get("https://api.example.com/data")
let data = response.json()  // parse JSON response
print(data["items"])

Examples

See the examples/ directory for 21 complete working examples:

• 01-hello-world: Simple label display
• 02-button-callback: Interactive button with state
• 03-form-input: Form with validation
• 04-table-display: Paginated table
• 05-progress-widgets: Progress bars and sliders
• 11-list: Virtualized scrolling list
• 12-tree: Hierarchical tree widget
• 13-http-fetch: HTTP requests and JSON
• 15-sql-test: Database connectivity
• 17-gridwrap: Grid layout
• 18-textgrid: Code display
• 19-richtext: Markdown formatting
• 20-button-importance: Button styling
• 21-form-validation: Entry validation

CLI Tool

The fynerisor command-line tool runs Risor GUI scripts:

fynerisor app.risor
fynerisor --watch app.risor              # auto-reload on changes
fynerisor --width 1024 --height 768 app.risor
fynerisor --headless app.risor           # for testing
fynerisor --globals data.json app.risor  # custom globals

Custom Globals

Inject custom data or functions into scripts:

import (
    "github.com/deepnoodle-ai/risor/v2"
    "github.com/uidbz/fynerisor/gui"
)

customData := risor.WithEnv(map[string]any{
    "api": myAPIObject,
    "config": configData,
})

fw := gui.NewApp("My App",
    gui.WithGlobals(customData),
)

Scripts can then access: api.someMethod() and config.someProperty