RubyGems - roxane - Versions diffs - 0.0.1-x64-mingw-ucrt - Mend

roxane 0.0.1-x64-mingw-ucrt

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

checksums.yaml +7 -0
data/LICENSE +21 -0
data/README.md +79 -0
data/assets/bridge.js +34 -0
data/lib/roxane/ffi.rb +51 -0
data/lib/roxane/static_server.rb +102 -0
data/lib/roxane/version.rb +5 -0
data/lib/roxane/window.rb +161 -0
data/lib/roxane.rb +40 -0
data/vendor/x64-mingw-ucrt/libwebview.dll +0 -0
metadata +70 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e2da1266447e9382b95782d156ac447cfe3370b324132ae707f36247f4e88ca5
+  data.tar.gz: 0d359d442a7cb58dffffafa269bd2a45d3ed1b430a38dca96a88443d29ad537e
+SHA512:
+  metadata.gz: c41309310016de49bf210438955f330274fe0bda6a12cd819bd163d402b2069226ba46280593285ae7e579e0eec60ce5e8072cb0c037b60a280dcdcca4bed70b
+  data.tar.gz: 2f9eb6dc4c63eb87170f5baa5ce5ee8f089831777696726350fd925bdbb4853c621975049dd53ff4702f11e35ba222117d273b40f198b8bd4a72126771c2e3f2

data/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 BKK Riese
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md ADDED Viewed

@@ -0,0 +1,79 @@
+# Roxane
+A pure-Ruby desktop shell: a native window over the operating system's webview
+(WebView2 / WKWebView / WebKitGTK, via the [webview](https://github.com/webview/webview)
+C library), with a Ruby⇄JS **operation bridge**. A lightweight, Tauri-shaped way
+to ship a web frontend as a desktop app — in Ruby.
+Named for Cyrano's Roxane.
+## What it is (and isn't)
+Roxane is the **host and data plane** — a window, the system webview, an
+`invoke`/`emit` bridge, and a loopback asset server. It serves whatever frontend
+you give it and is **agnostic to look-and-feel** (no CSS, no widgets, no layout
+opinions). The same frontend can run in the desktop shell and in a hosted browser.
+## Example
+```ruby
+require "roxane"
+win = Roxane::Window.new(title: "Hello", size: [900, 600])
+# JS → Ruby:  await window.roxane.invoke("greet", "world")
+win.on("greet") { |name| "Hello, #{name}!" }
+# Ruby → JS:  window.roxane.on("tick", ({ at }) => ...)
+win.emit("tick", { at: Time.now.to_i })
+win.serve(File.expand_path("ui"))   # serve a built frontend bundle, or:
+# win.load("http://localhost:5173") # point at a dev server, or:
+# win.html("<!doctype html>…")      # inline HTML
+win.run
+```
+Invocation handlers run **off the UI thread**, and `emit`/`eval` are safe from any
+thread — so long-running work (e.g. an AI call) never freezes the window.
+## Requirements
+The `webview` C library (`libwebview`) must be available at runtime. The
+precompiled platform gem (e.g. `x86_64-linux`) **vendors it**, so you only need
+the system webview runtime (WebKitGTK on Linux). Otherwise set `ROXANE_LIBWEBVIEW`
+to a `libwebview` path, or have it on the loader path.
+## Packaging (precompiled platform gems)
+Roxane ships a prebuilt `libwebview` per platform (the nokogiri model) so users
+need no toolchain. For x86_64-linux:
+```sh
+rake vendor:linux   # build libwebview into vendor/x86_64-linux/
+rake gem:linux      # build roxane-<ver>-x86_64-linux.gem (vendoring the lib)
+rake verify:linux   # install that gem in a clean container and smoke-test it
+```
+macOS / Windows / aarch64 cross-builds are next.
+## Testing
+```sh
+./run.sh        # Docker: Ruby + libwebview + headless Xvfb → full suite
+rake test       # host: unit tests only (the asset server); the windowed
+                # smoke test self-skips unless ROXANE_INTEGRATION=1
+```
+## Status
+Early but working. The runtime (window + system webview + invoke/emit bridge +
+loopback asset server) is green headlessly, and **precompiled x86_64-linux
+packaging works** — `rake verify:linux` builds the platform gem and proves it
+installs and runs on a clean machine (system WebKitGTK only, no toolchain). Next:
+macOS / Windows / aarch64 cross-builds + RubyGems publish, then richer window
+options (menus, frameless).
+## License
+MIT

data/assets/bridge.js ADDED Viewed

@@ -0,0 +1,34 @@
+// Roxane bridge — injected before page scripts. Defines window.roxane, the
+// symmetric counterpart to the Ruby Window API:
+//   window.roxane.invoke(op, payload) -> Promise   (Ruby `win.on(op){}`)
+//   window.roxane.on(event, cb) / off(event, cb)   (Ruby `win.emit(event, payload)`)
+(function () {
+  if (window.roxane) return;
+  var handlers = {}; // event name -> array of callbacks
+  window.roxane = {
+    // Call a Ruby operation handler; resolves with its return value (rejects on error).
+    invoke: function (op, payload) {
+      return window.__roxane_dispatch(op, payload === undefined ? null : payload);
+    },
+    // Subscribe to an event emitted from Ruby; returns an unsubscribe function.
+    on: function (event, cb) {
+      (handlers[event] || (handlers[event] = [])).push(cb);
+      return function () { window.roxane.off(event, cb); };
+    },
+    off: function (event, cb) {
+      var list = handlers[event];
+      if (!list) return;
+      var i = list.indexOf(cb);
+      if (i !== -1) list.splice(i, 1);
+    },
+    // Called by Ruby (via eval) to deliver an emitted event.
+    __receive: function (event, payload) {
+      var list = handlers[event];
+      if (!list) return;
+      list.slice().forEach(function (cb) {
+        try { cb(payload); } catch (e) { console.error("roxane handler for '" + event + "':", e); }
+      });
+    }
+  };
+})();

data/lib/roxane/ffi.rb ADDED Viewed

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+require "ffi"
+module Roxane
+  # Thin FFI binding to the maintained webview/webview C library. Resilient at load
+  # time: if libwebview can't be found (e.g. on a host without it yet), the gem
+  # still loads — `AVAILABLE` is false and `Window.new` raises a clear error —
+  # so pure-Ruby parts (the asset server) remain usable and testable.
+  module FFI
+    extend ::FFI::Library
+    HINT_NONE  = 0
+    HINT_MIN   = 1
+    HINT_MAX   = 2
+    HINT_FIXED = 3
+    begin
+      ffi_lib Roxane.library_path
+      # webview_t is an opaque pointer; setters return webview_error_t (int).
+      attach_function :webview_create,    [:int, :pointer],             :pointer
+      attach_function :webview_destroy,   [:pointer],                   :int
+      # blocking: true releases the GIL while the UI loop runs, so Ruby worker
+      # threads (engine/AI work) keep running alongside the webview.
+      attach_function :webview_run,       [:pointer],                   :int, blocking: true
+      attach_function :webview_terminate, [:pointer],                   :int
+      attach_function :webview_set_title, [:pointer, :string],          :int
+      attach_function :webview_set_size,  [:pointer, :int, :int, :int], :int
+      attach_function :webview_navigate,  [:pointer, :string],          :int
+      attach_function :webview_set_html,  [:pointer, :string],          :int
+      attach_function :webview_init,      [:pointer, :string],          :int
+      attach_function :webview_eval,      [:pointer, :string],          :int
+      callback :bind_fn, [:string, :string, :pointer], :void
+      attach_function :webview_bind,   [:pointer, :string, :bind_fn, :pointer], :int
+      attach_function :webview_return, [:pointer, :string, :int, :string],      :int
+      # dispatch runs a function on the UI thread — the safe way to call webview
+      # from worker threads (eval / return).
+      callback :dispatch_fn, [:pointer, :pointer], :void
+      attach_function :webview_dispatch, [:pointer, :dispatch_fn, :pointer], :int
+      AVAILABLE = true
+      LOAD_ERROR = nil
+    rescue LoadError, ::FFI::NotFoundError => e
+      AVAILABLE = false
+      LOAD_ERROR = e
+    end
+  end
+end

data/lib/roxane/static_server.rb ADDED Viewed

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+require "socket"
+require "uri"
+module Roxane
+  # Tiny loopback-only static file server — dependency-free (stdlib sockets). It
+  # serves a built frontend bundle to the embedded webview over a real http://
+  # origin, so ES modules / fetch / SPA routing behave (which file:// breaks), and
+  # the desktop path mirrors the hosted-web one (same frontend, local origin).
+  # GET-only, bound to 127.0.0.1, path-traversal-safe.
+  class StaticServer
+    MIME = {
+      ".html" => "text/html", ".htm" => "text/html",
+      ".js" => "text/javascript", ".mjs" => "text/javascript",
+      ".css" => "text/css", ".json" => "application/json", ".map" => "application/json",
+      ".svg" => "image/svg+xml", ".png" => "image/png", ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg", ".gif" => "image/gif", ".webp" => "image/webp",
+      ".ico" => "image/x-icon", ".woff" => "font/woff", ".woff2" => "font/woff2",
+      ".ttf" => "font/ttf", ".wasm" => "application/wasm", ".txt" => "text/plain"
+    }.freeze
+    attr_reader :root, :port
+    def initialize(root, spa: true)
+      @root = File.expand_path(root)
+      @spa = spa
+    end
+    # Start on an ephemeral loopback port in a background thread; returns base URL.
+    def start
+      @server = TCPServer.new("127.0.0.1", 0)
+      @port = @server.addr[1]
+      @thread = Thread.new { accept_loop }
+      "http://127.0.0.1:#{@port}/"
+    end
+    def stop
+      @server&.close
+      @thread&.kill
+    end
+    private
+    def accept_loop
+      loop { socket = @server.accept; Thread.new(socket) { |s| handle(s) } }
+    rescue IOError, Errno::EBADF
+      nil # server closed
+    end
+    def handle(socket)
+      request_line = socket.gets
+      return unless request_line
+      method, path, = request_line.split
+      while (line = socket.gets) && line != "\r\n"; end # drain headers
+      return respond(socket, 405, "text/plain", "method not allowed") unless method == "GET"
+      file = resolve(path)
+      if file
+        respond(socket, 200, mime(file), File.binread(file))
+      else
+        respond(socket, 404, "text/plain", "not found")
+      end
+    rescue Errno::EPIPE, Errno::ECONNRESET
+      nil # client went away
+    ensure
+      socket.close rescue nil
+    end
+    # Map a URL path to a file inside root, blocking traversal; SPA-fallback to
+    # index.html for extension-less routes.
+    def resolve(path)
+      rel = URI.decode_www_form_component(path.to_s.split("?", 2).first.to_s)
+      rel = "/index.html" if rel == "/" || rel.empty?
+      candidate = File.expand_path(File.join(@root, rel))
+      return nil unless candidate == @root || candidate.start_with?(@root + File::SEPARATOR)
+      return candidate if File.file?(candidate)
+      if @spa && File.extname(rel).empty?
+        index = File.join(@root, "index.html")
+        return index if File.file?(index)
+      end
+      nil
+    end
+    def mime(file)
+      MIME.fetch(File.extname(file).downcase, "application/octet-stream")
+    end
+    def respond(socket, status, type, body)
+      reason = { 200 => "OK", 404 => "Not Found", 405 => "Method Not Allowed" }.fetch(status, "OK")
+      body = body.to_s
+      socket.write("HTTP/1.1 #{status} #{reason}\r\n")
+      socket.write("Content-Type: #{type}\r\n")
+      socket.write("Content-Length: #{body.bytesize}\r\n")
+      socket.write("Cache-Control: no-cache\r\n")
+      socket.write("Connection: close\r\n\r\n")
+      socket.write(body)
+    end
+  end
+end

data/lib/roxane/version.rb ADDED Viewed

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+module Roxane
+  VERSION = "0.0.1"
+end

data/lib/roxane/window.rb ADDED Viewed

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+require "json"
+module Roxane
+  # A native window hosting the system webview, with a Ruby<->JS operation bridge.
+  # The shell/transport only: it serves whatever frontend you give it and is
+  # agnostic to look-and-feel.
+  #
+  #   win = Roxane::Window.new(title: "Hello", size: [900, 600])
+  #   win.on("greet") { |name| "Hello, #{name}!" }   # window.roxane.invoke("greet", "x")
+  #   win.emit("tick", { at: 1 })                     # window.roxane.on("tick", cb)
+  #   win.serve(File.expand_path("ui"))               # serve a built frontend dir
+  #   win.run
+  class Window
+    DISPATCH = "__roxane_dispatch" # the single C binding behind window.roxane.invoke
+    def initialize(title: "Roxane", size: [800, 600], min_size: nil, resizable: true, debug: false)
+      unless FFI::AVAILABLE
+        raise Error, "libwebview is not available (#{FFI::LOAD_ERROR}). " \
+                     "Set ROXANE_LIBWEBVIEW or install the webview C library."
+      end
+      @handlers  = {}        # operation name (String) -> handler block
+      @callbacks = []        # retained FFI::Function refs (must outlive the window)
+      @on_close  = nil
+      @server    = nil
+      @ui_queue  = Queue.new # procs to run on the UI thread
+      @w = FFI.webview_create(debug ? 1 : 0, nil)
+      raise Error, "could not create webview" if @w.null?
+      FFI.webview_set_title(@w, title.to_s)
+      apply_size(size, min_size, resizable)
+      install_ui_pump
+      install_bridge
+    end
+    # --- public API ---------------------------------------------------------
+    # Handle window.roxane.invoke(op, payload). The block runs OFF the UI thread;
+    # its return value resolves the JS promise, a raised error rejects it.
+    def on(op, &block)
+      @handlers[op.to_s] = block
+      self
+    end
+    # Push an event to the frontend (delivered to window.roxane.on(event, cb)).
+    # Safe to call from any thread.
+    def emit(event, payload = nil)
+      eval("window.roxane && window.roxane.__receive(#{JSON.generate(event.to_s)}, #{JSON.generate(payload)})")
+    end
+    # Run arbitrary JS in the page. Safe from any thread (marshalled to the UI thread).
+    def eval(js)
+      on_ui_thread { FFI.webview_eval(@w, js.to_s) }
+      self
+    end
+    # Low-level escape hatch: expose window.<name>(...args) -> Promise.
+    def bind(name, &block)
+      cb = ::FFI::Function.new(:void, [:string, :string, :pointer]) do |seq, req, _arg|
+        run_handler(seq) { block.call(*JSON.parse(req)) }
+      end
+      @callbacks << cb
+      FFI.webview_bind(@w, name.to_s, cb, nil)
+      self
+    end
+    # Serve a built frontend directory over loopback http and load it.
+    def serve(dir)
+      @server = StaticServer.new(dir)
+      load(@server.start)
+    end
+    def load(url)
+      FFI.webview_navigate(@w, url.to_s)
+      self
+    end
+    def html(markup)
+      FFI.webview_set_html(@w, markup.to_s)
+      self
+    end
+    def on_close(&block)
+      @on_close = block
+      self
+    end
+    # Run the native UI loop. Blocks the calling thread until the window closes.
+    def run
+      FFI.webview_run(@w)
+    ensure
+      @on_close&.call
+      @server&.stop
+      FFI.webview_destroy(@w)
+    end
+    # Stop the loop / close the window. Safe from any thread.
+    def close
+      FFI.webview_terminate(@w)
+    end
+    # --- internals ----------------------------------------------------------
+    private
+    def apply_size(size, min_size, resizable)
+      width, height = size
+      FFI.webview_set_size(@w, width, height, resizable ? FFI::HINT_NONE : FFI::HINT_FIXED)
+      FFI.webview_set_size(@w, min_size[0], min_size[1], FFI::HINT_MIN) if min_size && resizable
+    end
+    # One persistent dispatch callback drains a queue of procs on the UI thread —
+    # the safe way to call into webview from worker threads.
+    def install_ui_pump
+      @ui_pump = ::FFI::Function.new(:void, [:pointer, :pointer]) do |_w, _arg|
+        job = (@ui_queue.pop(true) rescue nil)
+        job&.call
+      end
+      @callbacks << @ui_pump
+    end
+    def on_ui_thread(&block)
+      @ui_queue << block
+      FFI.webview_dispatch(@w, @ui_pump, nil)
+    end
+    def install_bridge
+      cb = ::FFI::Function.new(:void, [:string, :string, :pointer]) do |seq, req, _arg|
+        op, payload = JSON.parse(req)
+        handler = @handlers[op]
+        if handler
+          run_handler(seq) { handler.call(payload) }
+        else
+          resolve(seq, 1, { "error" => "no handler for operation: #{op}" })
+        end
+      end
+      @callbacks << cb
+      FFI.webview_bind(@w, DISPATCH, cb, nil)
+      FFI.webview_init(@w, bridge_js)
+    end
+    # Run a handler off the UI thread, then resolve/reject the JS promise.
+    def run_handler(seq)
+      Thread.new do
+        resolve(seq, 0, yield)
+      rescue StandardError => e
+        resolve(seq, 1, { "error" => e.message })
+      end
+    end
+    def resolve(seq, status, value)
+      on_ui_thread { FFI.webview_return(@w, seq, status, JSON.generate(value)) }
+    end
+    def bridge_js
+      @bridge_js ||= File.read(File.expand_path("../../assets/bridge.js", __dir__))
+    end
+  end
+end

data/lib/roxane.rb ADDED Viewed

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+require "json"
+require "rbconfig"
+require_relative "roxane/version"
+# Roxane — a pure-Ruby desktop shell. A native window hosting the operating
+# system's webview (WebView2 / WKWebView / WebKitGTK, via the `webview` C library),
+# bridged to Ruby with an invoke/emit operation channel. The host/transport only:
+# it serves whatever web frontend you give it and is agnostic to look-and-feel.
+#
+# Named for Cyrano's Roxane.
+module Roxane
+  class Error < StandardError; end
+  # Path to the libwebview shared library: an explicit override wins, then a
+  # vendored (precompiled) copy shipped with the gem, then the platform's default
+  # name resolved by the system loader.
+  def self.library_path
+    ENV["ROXANE_LIBWEBVIEW"] || bundled_library || default_library_name
+  end
+  def self.bundled_library
+    platform_dir = File.join(__dir__, "..", "vendor", Gem::Platform.local.to_s)
+    Dir[File.join(platform_dir, "libwebview.{so,dylib,dll}*")].sort.first ||
+      Dir[File.join(__dir__, "..", "vendor", "**", "libwebview.{so,dylib,dll}*")].sort.first
+  end
+  def self.default_library_name
+    case RbConfig::CONFIG["host_os"]
+    when /darwin/                then "libwebview.dylib"
+    when /mswin|mingw|cygwin/    then "webview.dll"
+    else                              "libwebview.so"
+    end
+  end
+end
+require_relative "roxane/ffi"
+require_relative "roxane/static_server"
+require_relative "roxane/window"

data/vendor/x64-mingw-ucrt/libwebview.dll ADDED Viewed

Binary file

metadata ADDED Viewed

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: roxane
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: x64-mingw-ucrt
+authors:
+- BKK Riese
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+description: Roxane embeds the operating system's webview (WebView2 / WKWebView /
+  WebKitGTK, via the webview C library) in a native window and bridges it to Ruby
+  with an invoke/emit operation channel — a lightweight, Tauri-shaped way to ship
+  a web frontend as a desktop app, in Ruby.
+email:
+- brian@quarterstack.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- assets/bridge.js
+- lib/roxane.rb
+- lib/roxane/ffi.rb
+- lib/roxane/static_server.rb
+- lib/roxane/version.rb
+- lib/roxane/window.rb
+- vendor/x64-mingw-ucrt/libwebview.dll
+homepage: https://github.com/quarterstack/roxane
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'Pure-Ruby desktop shell: a native window over the system webview, bridged
+  to Ruby.'
+test_files: []