tokra 0.0.1.pre.1

data/doc/contributors/plan/001.md

@@ -0,0 +1,271 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Tokra Native Extension: Thin Rust Bindings Implementation
+
+This plan implements the native Rust extension layer for Tokra as specified in [ADR 001](file:///Users/kerrick/Developer/tokra/doc/contributors/adr/001.md). The extension provides thin Magnus bindings around `tao` (windowing) and `wry` (WebView), following the "dumb pipe" principle where Rust handles platform-native window/webview operations while Ruby manages all application logic, state, and routing.
+
+## User Review Required
+
+> [!IMPORTANT]
+> **Ruby 4.0.1 Compatibility**: Magnus 0.9.0 (unreleased, on main branch) explicitly supports Ruby 4.0. We'll use the git dependency until 0.9.0 is published to crates.io.
+
+> [!WARNING]
+> **Signal Handling**: When `tao` hijacks the main thread, Ruby's `Signal.trap("INT")` won't fire. The solution is to use the `ctrlc` crate in Rust to catch SIGINT and call `proxy.send_event(UserEvent::Exit)` to wake tao and allow clean shutdown.
+
+## Proposed Changes
+
+### Toolchain Configuration
+
+#### [MODIFY] [mise.toml](file:///Users/kerrick/Developer/tokra/mise.toml)
+
+Add Rust to the project's tool versions for consistent builds:
+
+```diff
+ [tools]
+ ruby = "4.0.1"
+ python = "3.12"
+ pre-commit = "latest"
++rust = "1.93.0"
+```
+
+---
+
+### Dependency Updates
+
+#### [MODIFY] [Cargo.toml](file:///Users/kerrick/Developer/tokra/ext/tokra/Cargo.toml)
+
+Update dependencies to latest compatible versions:
+
+```diff
+ [dependencies]
+-magnus = "0.7"
++magnus = { git = "https://github.com/matsadler/magnus", branch = "main" }
+-tao = "0.35"
++tao = "0.37"
+-wry = "0.52"
++wry = "0.52.2"
++ctrlc = "3.4"
+```
+
+Version notes:
+- `magnus` → Git main branch (0.9.0-dev) for Ruby 4.0 support, requires Rust 1.85+
+- `tao` 0.35.0 → 0.37.0 (two minor versions, contains API improvements)
+- `wry` 0.52.0 → 0.52.2 (patch updates, bug fixes)
+- `ctrlc` 3.4 → For SIGINT handling when tao owns the main thread
+- `rb-sys` 0.9.114 → Already at latest
+
+---
+
+### Core Implementation
+
+#### [MODIFY] [lib.rs](file:///Users/kerrick/Developer/tokra/ext/tokra/src/lib.rs)
+
+Complete implementation of the four Native classes per ADR 001 and ADR 002:
+
+**1. `Tokra::Native::EventLoop`**
+- Wraps `tao::event_loop::EventLoop<UserEvent>`
+- `run(callback: Proc)` → Starts the blocking event loop (never returns)
+- `create_proxy()` → Returns a `Tokra::Native::Proxy` for cross-Ractor communication
+- Handles `ctrlc` for SIGINT signal safety (since Ruby's `Signal.trap` won't work)
+- Fires callback on `UserEvent` and `WindowEvent` occurrences
+
+**2. `Tokra::Native::Window`** 
+- Wraps `tao::window::Window`
+- Constructor: `new(event_loop)`
+- Methods: `set_title(string)`, `set_size(width, height)`, `id()`
+
+**3. `Tokra::Native::WebView`**
+- Wraps `wry::WebView`
+- Constructor: `new(window, url, ipc_callback)` - The `ipc_callback` must be a `Ractor.shareable_proc`
+- `eval(js_string)` - Execute JavaScript in the webview
+- `register_protocol(scheme, callback)` - Register custom protocol handler; `callback` must be a `Ractor.shareable_proc`
+
+**4. `Tokra::Native::Proxy`**
+- Wraps `tao::event_loop::EventLoopProxy<UserEvent>`
+- `wake_up(payload)` - Thread-safe awakening from Ractors
+- Critical for Worker Ractor → Main Ractor communication
+
+**Implementation structure:**
+
+```rust
+// Custom UserEvent for cross-thread communication
+enum UserEvent {
+    IpcMessage(String),
+    WakeUp(String),
+    ProtocolRequest { scheme: String, request: ProtocolRequest },
+    Exit,
+}
+
+// Each Native class wraps its native type in a TypedData struct
+#[magnus::wrap(class = "Tokra::Native::EventLoop")]
+struct RbEventLoop { inner: RefCell<Option<EventLoop<UserEvent>>> }
+
+impl RbEventLoop {
+    fn create_proxy(&self) -> RbProxy { /* ... */ }
+    fn run(&self, callback: Proc) -> ! { /* ... */ }
+}
+
+#[magnus::wrap(class = "Tokra::Native::Window")]  
+struct RbWindow { inner: tao::window::Window }
+
+#[magnus::wrap(class = "Tokra::Native::WebView")]
+struct RbWebView { inner: WebView }
+
+impl RbWebView {
+    fn eval(&self, js: String) { /* ... */ }
+    fn register_protocol(&self, scheme: String, callback: Proc) { /* ... */ }
+}
+
+#[magnus::wrap(class = "Tokra::Native::Proxy")]
+struct RbProxy { inner: EventLoopProxy<UserEvent> }
+
+impl RbProxy {
+    fn wake_up(&self, payload: String) { /* ... */ }
+}
+```
+
+---
+
+### Ruby Integration
+
+#### [NEW] [lib/tokra/native.rb](file:///Users/kerrick/Developer/tokra/lib/tokra/native.rb)
+
+Ruby-side module to load and organize the Native classes:
+
+```ruby
+# frozen_string_literal: true
+
+module Tokra
+  module Native
+    # Native classes loaded from extension:
+    # - Tokra::Native::EventLoop
+    # - Tokra::Native::Window  
+    # - Tokra::Native::WebView
+    # - Tokra::Native::Proxy
+  end
+end
+
+require_relative "tokra/tokra"  # The native extension
+```
+
+#### [MODIFY] [lib/tokra.rb](file:///Users/kerrick/Developer/tokra/lib/tokra.rb)
+
+Add require for the Native module to the main entry point.
+
+---
+
+## Verification Plan
+
+### Automated Tests
+
+**Build verification:**
+```bash
+cd /Users/kerrick/Developer/tokra
+bundle exec rake compile
+```
+
+**Unit tests:**
+```bash
+bundle exec rake test
+```
+
+**Extension loading test:**
+```ruby
+require "tokra"
+# Should not raise LoadError
+
+# All Native classes should be defined
+Tokra::Native::EventLoop
+Tokra::Native::Window
+Tokra::Native::WebView
+Tokra::Native::Proxy
+```
+
+### Ping Pong Integration Test (ADR 003)
+
+The full round-trip validation test proving Ractor bridge, Main Loop, and IPC are functional:
+
+```ruby
+# test/integration/ping_pong_test.rb
+# frozen_string_literal: true
+
+require "tokra"
+require "timeout"
+
+class PingPongTest < Minitest::Test
+  def test_full_round_trip
+    Timeout.timeout(0.5) do  # 500ms for CI stability
+      # Communication ports (explicit Ractor::Port)
+      ipc_port = Ractor::Port.new
+      response_port = Ractor::Port.new
+
+      # Worker Ractor processes messages and responds via port
+      worker = Ractor.new(response_port) do |resp_port|
+        msg = Ractor.receive
+        resp_port << (msg + "PONG")
+      end
+
+      event_loop = Tokra::Native::EventLoop.new
+      proxy = event_loop.create_proxy
+      result = nil
+
+      # IPC handler must be a shareable_proc
+      ipc_handler = Ractor.shareable_proc do |raw_msg|
+        ipc_port << raw_msg
+      end
+
+      window = Tokra::Native::Window.new(event_loop)
+      webview = Tokra::Native::WebView.new(
+        window,
+        "data:text/html,<script>window.ipc.postMessage('PING')</script>",
+        ipc_handler
+      )
+
+      event_loop.run do |event|
+        case event
+        when Tokra::Native::IpcEvent
+          worker << event.message
+        when Tokra::Native::WakeUpEvent
+          result = response_port.receive
+          webview.eval("window.result = '#{result}'")
+          break
+        end
+      end
+
+      assert_equal "PINGPONG", result
+    end
+  end
+end
+```
+
+### Manual Verification
+
+**Interactive smoke test:**
+```ruby
+# frozen_string_literal: true
+
+require "tokra"
+
+event_loop = Tokra::Native::EventLoop.new
+proxy = event_loop.create_proxy
+window = Tokra::Native::Window.new(event_loop)
+window.set_title("Tokra Test")
+
+# IPC handler must be shareable
+ipc_handler = Ractor.shareable_proc do |msg|
+  puts "IPC received: #{msg}"
+end
+
+webview = Tokra::Native::WebView.new(window, "https://example.com", ipc_handler)
+
+# Opens a native window - visual confirmation
+event_loop.run do |event|
+  puts "Event received: #{event.inspect}"
+end
+```
+
+The window should appear, respond to resize/close, and properly terminate on Ctrl+C.

data/examples/verify_hello_world/app.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# !/usr/bin/env ruby
+
+# Hello World Example - Serve static index.html via tokra:// protocol
+#
+# This demonstrates that new_with_protocol works for simple static sites,
+# not just complex Rack-style apps. Just like Tauri's WebviewUrl::App("index.html").
+
+require_relative "../../lib/tokra"
+require "logger"
+
+# =============================================================================
+# Logging Setup
+# =============================================================================
+
+LOGGER = Logger.new($stdout)
+LOGGER.level = Logger::DEBUG
+LOGGER.progname = "HelloWorld"
+LOGGER.formatter = proc do |severity, datetime, progname, msg|
+  timestamp = datetime.strftime("%H:%M:%S.%L")
+  "#{timestamp} [#{severity.ljust(5)}] #{progname}: #{msg}\n"
+end
+
+# Read the static HTML file
+html_path = File.expand_path("index.html", __dir__)
+html_content = File.read(html_path)
+
+LOGGER.info { "=" * 50 }
+LOGGER.info { "Tokra Hello World" }
+LOGGER.info { "=" * 50 }
+LOGGER.debug { "Ruby version: #{RUBY_VERSION}" }
+LOGGER.debug { "Tokra version: #{Tokra::VERSION}" }
+LOGGER.info { "Serving: #{html_path}" }
+LOGGER.debug { "HTML content length: #{html_content.bytesize} bytes" }
+
+# Create the event loop and window
+LOGGER.debug { "Creating EventLoop" }
+event_loop = Tokra::Native::EventLoop.new
+
+LOGGER.debug { "Creating Proxy" }
+proxy = event_loop.create_proxy
+
+LOGGER.debug { "Creating Window" }
+window = Tokra::Native::Window.new(event_loop)
+window.set_title("Hello, Tokra!")
+window.set_size(600.0, 400.0)
+LOGGER.info { "Window created: 600x400, title='Hello, Tokra!'" }
+
+# Create WebView - navigates to tokra://localhost/
+LOGGER.debug { "Creating WebView with tokra:// protocol" }
+Tokra::Native::WebView.new_with_protocol(window, proxy)
+LOGGER.info { "WebView created, navigating to tokra://localhost/" }
+
+LOGGER.info { "-" * 50 }
+LOGGER.info { "Event loop starting..." }
+
+request_count = 0
+page_load_count = 0
+
+event_loop.run(
+  lambda { |event|
+    case event
+    when Tokra::Native::HttpRequestEvent
+      request_count += 1
+      request_id = event.request_id
+      method = event.method
+      uri = event.uri
+
+      LOGGER.info { "HTTP #{method} #{uri}" }
+      LOGGER.debug { "Request ##{request_count}, ID=#{request_id}" }
+
+      if method == "GET"
+        proxy.respond(
+          request_id,
+          200,
+          [["Content-Type", "text/html; charset=utf-8"]],
+          html_content
+        )
+        LOGGER.debug { "Responded with 200 OK, #{html_content.bytesize} bytes" }
+      else
+        proxy.respond(
+          request_id,
+          405,
+          [["Content-Type", "text/plain"]],
+          "Method Not Allowed"
+        )
+        LOGGER.debug { "Responded with 405 Method Not Allowed" }
+      end
+
+    when Tokra::Native::PageLoadEvent
+      page_load_count += 1
+      if event.started?
+        LOGGER.info { "Page load started: #{event.url}" }
+      else
+        LOGGER.info { "Page load finished: #{event.url}" }
+      end
+      LOGGER.debug { "Page load event ##{page_load_count}" }
+
+    when Tokra::Native::WindowCloseEvent
+      LOGGER.info { "-" * 50 }
+      LOGGER.info { "Window close requested" }
+      LOGGER.info { "Session stats: #{request_count} requests, #{page_load_count} page loads" }
+      LOGGER.info { "Goodbye!" }
+    end
+  }
+)
+
+LOGGER.info { "Event loop exited" }

data/examples/verify_hello_world/index.html

@@ -0,0 +1,88 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Tokra</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;600&display=swap" rel="stylesheet">
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; }
+
+    :root {
+      --text: oklch(25% 0.02 250);
+      --text-muted: oklch(50% 0.015 250);
+      --surface: oklch(98% 0.005 250);
+      --accent: oklch(55% 0.18 150);
+    }
+
+    html {
+      font-family: 'Instrument Sans', system-ui, sans-serif;
+      font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
+      line-height: 1.6;
+      color: var(--text);
+      background: var(--surface);
+    }
+
+    body {
+      min-height: 100dvh;
+      display: grid;
+      place-items: center;
+      padding: clamp(1.5rem, 4vw, 3rem);
+    }
+
+    main {
+      max-width: 32rem;
+    }
+
+    h1 {
+      font-size: clamp(2rem, 1.6rem + 2vw, 3rem);
+      font-weight: 600;
+      letter-spacing: -0.02em;
+      line-height: 1.1;
+      margin-block-end: 1.5rem;
+    }
+
+    p {
+      color: var(--text-muted);
+    }
+
+    p + p {
+      margin-block-start: 0.75rem;
+    }
+
+    code {
+      font-family: ui-monospace, 'SF Mono', 'Cascadia Code', monospace;
+      font-size: 0.9em;
+      background: oklch(94% 0.01 250);
+      padding: 0.15em 0.4em;
+      border-radius: 4px;
+    }
+
+    .status {
+      display: inline-block;
+      margin-block-start: 2rem;
+      padding: 0.5rem 1rem;
+      font-size: 0.85rem;
+      font-weight: 600;
+      color: var(--accent);
+      background: oklch(95% 0.04 150);
+      border-radius: 6px;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Hello from Tokra</h1>
+    <p>This page was served through the <code>tokra://</code> custom protocol, loaded directly from <code>index.html</code>.</p>
+    <p>Your Ruby app handles HTTP requests internally, just like Tauri does with <code>tauri://</code>.</p>
+    <span class="status">Protocol working</span>
+  </main>
+</body>
+</html>

data/examples/verify_ping_pong/app.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# !/usr/bin/env ruby
+# :nodoc:
+
+# Ping-Pong Verification Example - Real Roda App
+#
+# This demonstrates Tokra's Rack adapter with Roda: a real Roda application
+# running via the tokra:// custom protocol, just like Tauri's tauri://.
+
+require_relative "../../lib/tokra"
+require "roda"
+require "json"
+require "uri"
+require "stringio"
+require "securerandom"
+require "logger"
+
+# =============================================================================
+# Logging Setup
+# =============================================================================
+
+LOGGER = Logger.new($stdout)
+LOGGER.level = Logger::DEBUG
+LOGGER.progname = "PingPong"
+LOGGER.formatter = proc do |severity, datetime, progname, msg|
+  timestamp = datetime.strftime("%H:%M:%S.%L")
+  "#{timestamp} [#{severity.ljust(5)}] #{progname}: #{msg}\n"
+end
+
+MESSAGE = ARGV[0] || "Default message - pass an argument!" # :nodoc:
+
+LOGGER.info { "Starting Ping-Pong verification example" }
+LOGGER.debug { "Ruby version: #{RUBY_VERSION}" }
+LOGGER.debug { "Tokra version: #{Tokra::VERSION}" }
+LOGGER.debug { "Message argument: #{MESSAGE.inspect}" }
+
+# =============================================================================
+# The Roda Application
+# =============================================================================
+
+class PingPongApp < Roda
+  # Session secret - just needs to be consistent for this process
+  plugin :sessions, secret: SecureRandom.hex(32)
+  plugin :flash
+  plugin :render, views: File.expand_path("views", __dir__), escape: true
+  plugin :json
+  plugin :all_verbs
+  plugin :public, root: File.expand_path("public", __dir__)
+
+  # Store message in opts so it's accessible in route block
+  opts[:message] = MESSAGE
+  opts[:logger] = LOGGER
+
+  route do |r|
+    opts[:logger].debug { "Routing: #{r.request_method} #{r.path}" }
+
+    # Serve static assets from public/
+    r.public
+
+    # GET / - serve the main page
+    r.root do
+      opts[:logger].info { "Serving index page" }
+      opts[:logger].debug { "Flash contents: #{flash.inspect}" }
+      view("index", locals: { message: opts[:message], flash: })
+    end
+
+    # POST /submit - handle form submission, redirect back
+    r.post "submit" do
+      response = r.params["response"]
+      opts[:logger].info { "Form submission received" }
+      opts[:logger].debug { "Form response value: #{response.inspect}" }
+
+      flash["success"] = "Form submitted! You said: \"#{response}\""
+      opts[:logger].debug { "Flash set, redirecting to root" }
+
+      r.redirect "tokra://localhost/"
+    end
+
+    # POST /api - JSON API endpoint
+    r.post "api" do
+      body = r.body.read
+      opts[:logger].info { "API request received" }
+      opts[:logger].debug { "API request body: #{body.inspect}" }
+
+      data = begin
+        JSON.parse(body)
+      rescue
+        { "raw" => body }
+      end
+      opts[:logger].debug { "Parsed API data: #{data.inspect}" }
+
+      response = {
+        status: "ok",
+        received: data,
+        timestamp: Time.now.iso8601,
+      }
+      opts[:logger].debug { "API response: #{response.inspect}" }
+
+      response
+    end
+  end
+end
+
+LOGGER.info { "Roda application class defined" }
+LOGGER.debug { "Plugins loaded: sessions, flash, render, json, all_verbs" }
+
+# =============================================================================
+# Run the app
+# =============================================================================
+
+LOGGER.info { "=" * 50 }
+LOGGER.info { "Tokra Ping-Pong (Roda App)" }
+LOGGER.info { "=" * 50 }
+
+LOGGER.debug { "Freezing Roda app" }
+rack_app = PingPongApp.freeze.app
+LOGGER.info { "Starting Rack::Handler::Tokra.run" }
+
+Rack::Handler::Tokra.run(
+  rack_app,
+  title: "Tokra Ping-Pong",
+  width: 500,
+  height: 600
+)
+
+LOGGER.info { "Event loop exited" }