README.md — lantern

1# Lantern

3Lantern is a Sigil-native desktop wrapper for web apps: point it at a Sigil web

4build (wasm + assets) and get a native desktop app with a real window and a

5secure JS to Sigil bridge, built all the way down in Sigil over `sigil-ffi`. No

6Rust, no Node, no C glue: the GTK4 + WebKitGTK backend is bound through dynamic

7FFI. Linux-first (WebKitGTK); the backend interface leaves room for macOS and

8Windows later.

10## Packages

12- **`lantern`** the framework library: a backend-neutral webview interface, the

13 GTK/WebKitGTK backend, the `lantern://` asset scheme, the JS to Sigil bridge

14 protocol, the command registry, and the plugin system. App-agnostic.

15- **`lantern-cli`** a thin runner: `lantern run <dir|url>` opens any web build in

16 a native Lantern window with the built-in command set.

17- **`examples/lantern-demo`** a minimal app proving the bridge: a custom command,

18 a host to page event, and the plain-browser fallback.

20## Architecture

22```

23(lantern app) manifest, command registry, lifecycle, lantern-run

24(lantern bridge) JS <-> Sigil protocol: enqueue, dispatch, resolve/reject/events

25(lantern webview) backend-neutral webview interface (the narrow waist)

26(lantern backend gtk) WebKitGTK 6.0 over GTK4, pure sigil-ffi

27(lantern gobject) GObject refcount / signal / finalizer idioms

28(lantern serve) the lantern:// asset resolver

29(lantern loop) the main-thread pump

30(lantern js) lantern.js, the injected page-side glue

31```

33The page talks to the host through one channel: `lantern.invoke(cmd, args)`

34returns a Promise; `lantern.on(event, fn)` subscribes to host events;

35`lantern.available` feature-detects the bridge, so the same web build runs

36unmodified in a plain browser (progressive enhancement). The page may invoke only

37commands the app registered; nothing page-supplied is evaluated as Sigil, and the

38bridge is injected only for the `lantern://app` origin, top frame.

40## Building and running

42Lantern needs the GTK4 + WebKitGTK graphics stack, and on distributions that do

43not put it on the default loader path (e.g. Guix) you must make it findable:

45- Set `LANTERN_LIB_DIR` to the directory holding `libgtk-4.so.1`,

46 `libwebkitgtk-6.0.so.4`, etc., or

47- put that directory on `LD_LIBRARY_PATH`.

49GTK4 also needs the Mesa GL/Vulkan drivers present, or it commits no frame and

50the window never appears (no error). On Guix, pin a profile with

51`gtk webkitgtk glib glib-networking mesa libglvnd` and run inside it.

53```sh

54sigil deps install

55sigil build lantern-cli --config native # native: enables >=4-arg callbacks

56./build/native/bin/lantern run ./path/to/web-build

57```

59`LANTERN_SOFTWARE_RENDER=1` forces WebKit software rendering on hosts whose GPU

60stack cannot drive its threaded compositor.

62## Status

64Phases 1 and 2 of the design: the webview interface + GTK backend + window +

65`lantern://` scheme (Phase 1), and the bridge protocol + registry + manifest +

66`lantern.js` + origin gating (Phase 2). The main loop is the async Option-A pump

67(requires sigil-ffi 0.16.3), so command handlers run as goroutines and may freely

68await. Desktop-integration modules (clipboard, dialogs, notifications, menus) are

69later phases.