Lantern

Lantern is a Sigil-native desktop wrapper for web apps: point it at a Sigil web build (wasm + assets) and get a native desktop app with a real window and a secure JS to Sigil bridge, built all the way down in Sigil over sigil-ffi. No Rust, no Node, no C glue: the GTK4 + WebKitGTK backend is bound through dynamic FFI. Linux-first (WebKitGTK); the backend interface leaves room for macOS and Windows later.

Packages

• lantern the framework library: a backend-neutral webview interface, the GTK/WebKitGTK backend, the lantern:// asset scheme, the JS to Sigil bridge protocol, the command registry, and the plugin system. App-agnostic.
• lantern-cli a thin runner: lantern run <dir|url> opens any web build in a native Lantern window with the built-in command set.
• examples/lantern-demo a minimal app proving the bridge: a custom command, a host to page event, and the plain-browser fallback.

Architecture

(lantern app)        manifest, command registry, lifecycle, lantern-run
(lantern bridge)     JS <-> Sigil protocol: enqueue, dispatch, resolve/reject/events
(lantern webview)    backend-neutral webview interface (the narrow waist)
(lantern backend gtk)  WebKitGTK 6.0 over GTK4, pure sigil-ffi
(lantern gobject)    GObject refcount / signal / finalizer idioms
(lantern serve)      the lantern:// asset resolver
(lantern loop)       the main-thread pump
(lantern js)         lantern.js, the injected page-side glue

The page talks to the host through one channel: lantern.invoke(cmd, args) returns a Promise; lantern.on(event, fn) subscribes to host events; lantern.available feature-detects the bridge, so the same web build runs unmodified in a plain browser (progressive enhancement). The page may invoke only commands the app registered; nothing page-supplied is evaluated as Sigil, and the bridge is injected only for the lantern://app origin, top frame.

Building and running

Lantern needs the GTK4 + WebKitGTK graphics stack, and on distributions that do not put it on the default loader path (e.g. Guix) you must make it findable:

• Set LANTERN_LIB_DIR to the directory holding libgtk-4.so.1, libwebkitgtk-6.0.so.4, etc., or
• put that directory on LD_LIBRARY_PATH.

GTK4 also needs the Mesa GL/Vulkan drivers present, or it commits no frame and the window never appears (no error). On Guix, pin a profile with gtk webkitgtk glib glib-networking mesa libglvnd and run inside it.

sigil deps install
sigil build lantern-cli --config native      # native: enables >=4-arg callbacks
./build/native/bin/lantern run ./path/to/web-build

LANTERN_SOFTWARE_RENDER=1 forces WebKit software rendering on hosts whose GPU stack cannot drive its threaded compositor.

Status

Phases 1 and 2 of the design: the webview interface + GTK backend + window + lantern:// scheme (Phase 1), and the bridge protocol + registry + manifest + lantern.js + origin gating (Phase 2). The main loop is the async Option-A pump (requires sigil-ffi 0.16.3), so command handlers run as goroutines and may freely await. Desktop-integration modules (clipboard, dialogs, notifications, menus) are later phases.