ruby_everywhere 0.4.0 → 0.6.0

data/support/agents/frameworks/sinatra-views.md

@@ -0,0 +1,24 @@
+### Native chrome from your views
+
+The ERB helpers (`native_app?`, `everywhere_nav_button`, `everywhere_fab`, …) ship with the
+Rails engine, so they aren't available here. The markup contract behind them is public,
+though, and the shell watches for it on every Turbo visit — write it directly:
+
+- `data-everywhere-nav-button` (+ `-nav-title`, `-nav-icon`, `-nav-icon-ios`,
+  `-nav-icon-android`, `-nav-style`, `side`) — lifts a link or submit button into the top
+  navigation bar. Tapping the native control clicks your element.
+- `data-everywhere-nav-menu` with `data-everywhere-menu-item` children (+ `-menu-title`,
+  `-menu-style`) — a native pull-down menu.
+- `data-everywhere-menu` + `-menu-trigger` + `-menu-items` — an in-content action sheet.
+- `data-everywhere-haptic` — a tap haptic.
+- `data-everywhere-biometric-lock` (+ `-content`, `-locked`, `-unlock`, `-reason`,
+  `-passcode`) — the Face ID / Touch ID gate.
+- `<meta name="everywhere:badge">` and `<meta name="everywhere:tab-badge">` (JSON
+  `{path, count}`) — app-icon and tab badges, CSP-safe and correct on first paint.
+
+Detect the shell server-side from the User-Agent: the shells prepend
+`RubyEverywhere/<version> (<os>)` to Hotwire Native's own marker. Client-side, use
+`Everywhere.platform` / `Everywhere.native`.
+
+`public/native.css` carries the styling helpers, including `.everywhere-titlebar-inset` for
+`window.title_bar: overlay`.

data/support/agents/frameworks/sinatra.md

@@ -0,0 +1,9 @@
+- `native_boot.rb` — the packaged-app entry point. Keep it thin and keep it at the app root.
+- `public/bridge.js` and `public/native.css` — the bridge, vendored and refreshed on each
+  `every install`. Load it with `<script type="module" src="/bridge.js"></script>`.
+
+Rack apps vary too much for the CLI to auto-edit their boot files, so the rest is by hand and
+`every install` prints it rather than guessing: point the production SQLite path at
+`ENV.fetch("NATIVE_STORAGE_DIR", "storage")`, and call
+`Everywhere::Database.prepare!(__dir__)` from `config.ru` after loading the app. Both only
+matter for on-device packaging.

data/support/agents/modes/local.md

@@ -0,0 +1,12 @@
+The app itself is compiled into the shipped binary and runs on the user's machine, rather than
+the shells pointing at a deployed site. Shipping a change means cutting a new build and
+release.
+
+That trade brings constraints the docs cover properly — a read-only application filesystem
+with a separate writable data directory, SQLite only, desktop only — so read
+<https://rubyeverywhere.com/docs> before changing anything that writes to disk, boots the app,
+or touches `native_boot.rb`. The short version: anything written at runtime belongs under
+`ENV.fetch("NATIVE_STORAGE_DIR", "storage")`, and `ENV["NATIVE_PACKAGED"]` is the guard for
+packaged-only behavior.
+
+Everything below applies the same way in either mode.

data/support/agents/modes/remote.md

@@ -0,0 +1,14 @@
+The native shells are a thin wrapper around the deployed site at `remote.url` in
+`config/everywhere.yml`. Nothing about the app is compiled into them.
+
+**So you are working on an ordinary web app.** Ship a change by deploying as you always have,
+and users see it on their next launch — no rebuild, no app-store review. Normal databases,
+background jobs, and hosting all apply, unchanged.
+
+Only three things are native-specific, and they're all covered below: what
+`config/everywhere.yml` declares, the view markup that becomes native chrome, and the
+`Everywhere` JavaScript API. Of those, tab and path-rule changes deploy with the app; the rest
+of `config/everywhere.yml` needs a new build of the shells.
+
+Remote is also the only mode mobile supports — iOS and Android are always a shell around a
+deployed app.

data/support/desktop/README.md

@@ -0,0 +1,121 @@
+# The RubyEverywhere desktop shell
+
+A [Tauri](https://tauri.app) v2 app that boots a packaged Rails binary as a
+sidecar and shows it in a webview — or, in remote mode, wraps an already-deployed
+app. This directory is the canonical copy; the CLI resolves it with
+`Everywhere::Paths.shell_dir` and external consumers with `every shell-dir`.
+
+```
+src-tauri/
+  src/main.rs             boot, window, menu, tray, config, assets
+  src/updater.rs          signed self-updates
+  src/extension_host.rs   the event bridge extension commands answer on
+  src/extensions/mod.rs   GENERATED — the app's Rust registry
+  Cargo.toml              carries the __EVERYWHERE_APP_CRATES__ marker
+  tauri.conf.json         near-empty on purpose (see below)
+  capabilities/default.json
+splash/index.html         frontendDist — shown while the sidecar boots
+```
+
+## One binary, every app
+
+Unlike the iOS and Android templates, this shell is **not** stamped per app by
+default. One crate serves every RubyEverywhere app, and everything per-app
+arrives at runtime as JSON — `NATIVE_CONFIG` under `every dev`,
+`Contents/Resources/everywhere.json` inside a packaged `.app`.
+
+That's why `tauri.conf.json` declares `"windows": []` and `"bundle": {"active":
+false}`: window properties are set at runtime in `build_window`, and the `.app`
+is assembled by hand in `Commands::Build#bundle_app` rather than by `tauri-cli`.
+`productName` and `identifier` in that file never reach a built app: an app's
+name comes from `CFBundleName` in the hand-written plist (and, under `every dev`,
+from the throwaway `.app` wrapper `Commands::Dev#stage_dev_bundle` assembles),
+and its bundle id from `everywhere.yml`.
+
+They do still name things on disk, so they aren't free to change. `identifier`
+keys Tauri's own app-config directory, which is where `tauri-plugin-window-state`
+writes each app's saved geometry. Everything an app would actually miss is keyed
+by its own `bundle_id` under the plain OS data dir instead — app data (see the
+comment above the `app_data` binding in `main.rs`), the updater's channel choice,
+and the Windows/Linux webview profile — so changing `identifier` costs one
+forgotten window size per app and nothing else.
+
+The payoff is that `cargo` compiles this once per machine, against the shared
+`~/.rubyeverywhere/shell-target`, and stays warm across every project.
+
+## The freeze contract
+
+An app that declares `native.desktop` in `config/everywhere.yml` **does** get a
+stamped copy, under `~/.rubyeverywhere/desktop/<bundle_id>/`, with its own
+target dir. `Builders::Desktop` writes exactly these files there and nothing
+else:
+
+1. `src-tauri/Cargo.toml` — the template's, with `native.desktop.crates`
+   substituted into the `# __EVERYWHERE_APP_CRATES__` marker. Cargo has no
+   include mechanism, so unlike Android's `native-packages.gradle.kts` the crate
+   list cannot live in its own file.
+2. `src-tauri/src/extensions/**` — the app's `native/desktop/**/*.rs`, copied
+   preserving relative paths, plus a generated `mod.rs` in every directory.
+
+Everything else is the frozen template, copied as-is. In particular
+`src/main.rs`, `src/extension_host.rs`, `capabilities/default.json` and
+`tauri.conf.json` are **never** rewritten — if a feature seems to need editing
+one of them per app, it belongs in the runtime config instead.
+
+`mod.rs` is reserved at every level: the builder refuses to run if the app ships
+one, rather than silently overwriting it.
+
+The stamped dir is merged into, not wiped, so cargo's incremental state
+survives — except on a gem version change, where the marker `.everywhere-template`
+mismatches and the whole thing is rebuilt.
+
+### The three seams in main.rs
+
+Adding an extension point means touching `main.rs`, which the contract above
+forbids per app. These are the ones that exist, and they should stay the only
+ones:
+
+- `mod extensions;` / `mod extension_host;`
+- `.invoke_handler(extensions::handler())`
+- `extensions::setup(app)?` in the Tauri setup closure
+
+The checked-in `src/extensions/mod.rs` registers nothing, so the bare template
+compiles green on its own.
+
+## Why extensions use events, not `invoke`
+
+Tauri v2 refuses IPC `invoke` from any `http` origin — and a RubyEverywhere page
+is *always* http, whether that's `127.0.0.1` in local mode or your own domain in
+remote mode. Granting the origin in `capabilities/default.json` doesn't change
+it; a registered command still fails with `not allowed. Plugin not found`.
+
+So extension commands are plain functions with a uniform signature:
+
+```rust
+pub fn scan_ports(app: &tauri::AppHandle, payload: serde_json::Value)
+    -> Result<serde_json::Value, String>
+```
+
+reached over an event pair (`everywhere:command` →
+`everywhere:command-result`), which is the same path `Everywhere.notify` has
+always used. `extension_host.rs` owns that protocol; the generated
+`extensions/mod.rs` only supplies the `match` over command names.
+
+## Working on the shell
+
+```sh
+# run it against any URL, no CLI needed
+NATIVE_DEV_URL=http://localhost:3000 \
+NATIVE_CONFIG='{"name":"Test","bundle_id":"com.example.test"}' \
+CARGO_TARGET_DIR=~/.rubyeverywhere/shell-target cargo run
+
+# or point the CLI at a modified checkout
+every dev --shell-dir /path/to/src-tauri
+```
+
+Other env vars `main.rs` reads: `NATIVE_ASSETS_DIR` (staged
+`native/desktop/assets`), `NATIVE_NAVIGATE_URL` (splash→navigate flow without a
+sidecar), `NATIVE_SIDECAR_PATH`.
+
+`--shell-dir` points at the `src-tauri` directory; the builder stages its parent,
+because `frontendDist` is `../splash`.

data/support/{shell → desktop}/src-tauri/Cargo.lock

@@ -995,6 +995,7 @@ version = "0.2.0"
 dependencies = [
  "minisign-verify",
  "objc2",
+ "objc2-app-kit",
  "objc2-foundation",
  "objc2-web-kit",
  "semver",
@@ -2258,10 +2259,17 @@ checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
 dependencies = [
  "bitflags 2.13.0",
  "block2",
+ "libc",
  "objc2",
+ "objc2-cloud-kit",
+ "objc2-core-data",
  "objc2-core-foundation",
  "objc2-core-graphics",
+ "objc2-core-image",
+ "objc2-core-text",
+ "objc2-core-video",
  "objc2-foundation",
+ "objc2-quartz-core",
 ]
 
 [[package]]
@@ -2281,6 +2289,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b402a653efbb5e82ce4df10683b6b28027616a2715e90009947d50b8dd298fa"
 dependencies = [
+ "bitflags 2.13.0",
  "objc2",
  "objc2-foundation",
 ]
@@ -2341,6 +2350,19 @@ dependencies = [
  "objc2-core-graphics",
 ]
 
+[[package]]
+name = "objc2-core-video"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d425caf1df73233f29fd8a5c3e5edbc30d2d4307870f802d18f00d83dc5141a6"
+dependencies = [
+ "bitflags 2.13.0",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-io-surface",
+]
+
 [[package]]
 name = "objc2-encode"
 version = "4.1.0"
@@ -3624,6 +3646,7 @@ dependencies = [
  "gtk",
  "heck 0.5.0",
  "http",
+ "image",
  "jni",
  "libc",
  "log",

data/support/{shell → desktop}/src-tauri/Cargo.toml

@@ -8,7 +8,13 @@ edition = "2021"
 tauri-build = { version = "2", features = [] }
 
 [dependencies]
-tauri = { version = "2", features = ["devtools", "webview-data-url", "tray-icon"] }
+# image-png / image-ico back Image::from_path, which loads the app's `tray`
+# asset (native/desktop/assets) for the menu bar.
+#
+# Deliberately NOT here: macos-private-api. It's what a transparent macOS window
+# needs, and Apple has rejected Mac App Store submissions over it — not a tax
+# worth charging every app for a look none of them have asked for yet.
+tauri = { version = "2", features = ["devtools", "webview-data-url", "tray-icon", "image-png", "image-ico"] }
 serde_json = "1"
 tauri-plugin-notification = "2"
 tauri-plugin-dialog = "2"
@@ -21,6 +27,14 @@ semver = "1"
 sha2 = "0.10"
 minisign-verify = "0.2"
 
+# Crates the app declares under `native.desktop.crates` are substituted in here
+# when the shell is stamped per app. Cargo has no include/apply-from mechanism —
+# unlike Android's native-packages.gradle.kts, the list can't be its own file —
+# so the CLI rewrites this marker in the STAMPED copy under ~/.rubyeverywhere.
+# The gem's own Cargo.toml is never edited. Keep this line last in [dependencies]
+# (the macOS target table below has to stay a separate section).
+# __EVERYWHERE_APP_CRATES__
+
 # macOS: set the WebView's `applicationNameForUserAgent`, which WKWebView
 # natively APPENDS to its real default UA — so we get the true system UA plus
 # our marker without ever reading or hardcoding the base string. Versions are
@@ -29,6 +43,10 @@ minisign-verify = "0.2"
 objc2 = "0.6"
 objc2-foundation = { version = "0.3", features = ["NSString", "NSUUID", "NSProcessInfo"] }
 objc2-web-kit = { version = "0.3", features = ["WKWebViewConfiguration", "WKWebsiteDataStore"] }
+# Dock icon + menu-bar app name under `every dev`, where there's no .app bundle
+# for macOS to read either from. Already in the tree via tao/muda; pinned to the
+# same 0.3 line so no duplicate objc2 crates appear.
+objc2-app-kit = { version = "0.3", features = ["NSApplication", "NSImage", "NSResponder"] }
 
 [profile.release]
 strip = true

data/support/{shell → desktop}/src-tauri/capabilities/default.json

@@ -14,6 +14,13 @@
   "permissions": [
     "core:default",
     "core:window:allow-set-title",
+    "core:window:allow-minimize",
+    "core:window:allow-maximize",
+    "core:window:allow-unmaximize",
+    "core:window:allow-toggle-maximize",
+    "core:window:allow-close",
+    "core:window:allow-is-maximized",
+    "core:window:allow-start-dragging",
     "notification:default",
     "dialog:default",
     "clipboard-manager:allow-read-text",

data/support/desktop/src-tauri/gen/schemas/capabilities.json

@@ -0,0 +1 @@
+{"default":{"identifier":"default","description":"Main window IPC: local app origins (the packaged Rails app serves on 127.0.0.1)","remote":{"urls":["http://127.0.0.1:*","http://localhost:*"]},"local":true,"windows":["main"],"permissions":["core:default","core:window:allow-set-title","core:window:allow-minimize","core:window:allow-maximize","core:window:allow-unmaximize","core:window:allow-toggle-maximize","core:window:allow-close","core:window:allow-is-maximized","core:window:allow-start-dragging","notification:default","dialog:default","clipboard-manager:allow-read-text","clipboard-manager:allow-write-text"]}}

data/support/desktop/src-tauri/src/extension_host.rs

@@ -0,0 +1,53 @@
+// The machinery behind native/desktop/ extensions. Frozen shell code — unlike
+// src/extensions/mod.rs next door, the CLI never rewrites this file.
+//
+// Pages reach extension Rust over EVENTS, not Tauri's invoke. That isn't a
+// remote-mode workaround, it's the only thing that works: a RubyEverywhere page
+// is always served over http — 127.0.0.1 in local mode, your own domain in
+// remote mode — and Tauri v2 refuses invoke from any http origin, including the
+// packaged app's own localhost server. (Verified: invoking a registered command
+// from http://127.0.0.1 fails with "not allowed. Plugin not found" even with
+// the origin granted in capabilities/default.json.) Events are the sanctioned
+// path for non-tauri:// content, and they're what Everywhere.notify has always
+// used.
+//
+// Protocol, mirroring the bridge's Everywhere.desktop.invoke():
+//
+//   page  -> shell   everywhere:command         { id, name, payload }
+//   shell -> page    everywhere:command-result  { id, ok: true,  value }
+//                                               { id, ok: false, error }
+//
+// The id round-trips so concurrent calls can't take each other's answers.
+
+use tauri::{Emitter, Listener};
+
+// What a generated dispatcher looks like. One uniform signature rather than
+// Tauri's typed-argument commands, because typed commands only ever arrive
+// through invoke — which, per above, our pages can't use.
+pub type Dispatch = fn(&tauri::AppHandle, &str, serde_json::Value) -> Result<serde_json::Value, String>;
+
+pub fn install_command_bridge(app: &tauri::App, dispatch: Dispatch) {
+    let handle = app.handle().clone();
+    app.listen_any("everywhere:command", move |event| {
+        let request: serde_json::Value =
+            serde_json::from_str(event.payload()).unwrap_or(serde_json::Value::Null);
+        let id = request["id"].as_str().unwrap_or_default().to_string();
+        let name = request["name"].as_str().unwrap_or_default().to_string();
+        let payload = request["payload"].clone();
+        let handle = handle.clone();
+
+        // Off the event thread: an extension command is app code that may well
+        // block on a port, a file, or an HTTP call, and running it inline would
+        // stall every other event behind it. The id in the reply means answers
+        // coming back out of order costs nothing.
+        std::thread::spawn(move || {
+            let reply = match dispatch(&handle, &name, payload) {
+                Ok(value) => serde_json::json!({ "id": id, "ok": true, "value": value }),
+                Err(message) => serde_json::json!({ "id": id, "ok": false, "error": message }),
+            };
+            if let Err(e) = handle.emit("everywhere:command-result", reply) {
+                eprintln!("[extensions] couldn't answer command {name}: {e}");
+            }
+        });
+    });
+}

data/support/desktop/src-tauri/src/extensions/mod.rs

@@ -0,0 +1,39 @@
+// GENERATED by `every build` / `every dev` from `native.desktop` in the app's
+// config/everywhere.yml. THIS COPY REGISTERS NOTHING — it exists so the bare
+// template still compiles and so the seams in main.rs have something to call.
+//
+// An app that declares Rust extensions gets a stamped copy of this shell under
+// ~/.rubyeverywhere/desktop/<bundle_id>, where this file is rewritten to name
+// the app's own modules and commands, and the app's .rs files sit beside it.
+// Don't edit it by hand: it is overwritten on every build. App code belongs in
+// native/desktop/ in the app repo.
+//
+// See support/desktop/README.md for the freeze contract.
+
+use crate::commands;
+
+// Every command the shell exposes over Tauri's IPC. Extracted into a function
+// so the generator owns one file instead of editing main.rs: generate_handler!
+// has to name every command in a single list.
+//
+// This is the shell's OWN commands only. App extensions are reached over events
+// instead — see extension_host.rs for why invoke isn't available to them.
+pub fn handler() -> impl Fn(tauri::ipc::Invoke<tauri::Wry>) -> bool + Send + Sync + 'static {
+    tauri::generate_handler![commands::notify_command]
+}
+
+// Runs once at boot, before any window exists.
+pub fn setup(app: &tauri::App) -> Result<(), Box<dyn std::error::Error>> {
+    crate::extension_host::install_command_bridge(app, dispatch);
+    Ok(())
+}
+
+// Routes an Everywhere.desktop.invoke(name, payload) call to the app's Rust.
+// The generated version matches on every name in `native.desktop.commands`.
+fn dispatch(
+    _app: &tauri::AppHandle,
+    name: &str,
+    _payload: serde_json::Value,
+) -> Result<serde_json::Value, String> {
+    Err(format!("no desktop command named {name:?} — declare it under native.desktop.commands"))
+}