ruby_everywhere 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b255975aa8724cb4980606ddbde415eea3a238c193ffce8530028ef5fdc63c24
-  data.tar.gz: 386145d42d750984da4fa800ea9b63417371937dbf67d49642a229cd92cfbb71
+  metadata.gz: b4e222fd8e74b0c921b4cdab9d681b0f06bad2d94aae8dbe999415824508a1f5
+  data.tar.gz: e3a49bb93e2e49924c70cb622943e02b9bb302ddb828d29fc4c2ee5064c01e0e
 SHA512:
-  metadata.gz: 6af24db6e60c693ae855fa47832564074d887c18248a63be23c343c5e85c7d84cf4210017ba6bb26dae9950bb6b1394255f02cbea4d278f9407952a22f37dd6c
-  data.tar.gz: 368f12504a2a5748aa30eaf641eadf5b85bbd54b99e0f372015b9621510f01dc5779ca6e3e37cfab594083768815e40e48200e2c3649195c5b5e800cc7cf5557
+  metadata.gz: 5756a97bf1012daf2069fdb186de16f22a1bdbed9972ec42e384dc8b9b24a84b03b004568af26eeb6990b53336ceb3bfd6c4f3177ec9b0b43e2682db15b382a1
+  data.tar.gz: aba1e8c877b1ecd3b9b975a434c89831a9a0b302cbc2bea567472d650f28a442666735cfb9171a20aa615894c7e9bd5de52d2f9e334b7b9af00f750489fac14f

data/README.md

@@ -0,0 +1,339 @@
+# RubyEverywhere
+
+**Ship desktop and mobile apps from the Ruby web apps you already know how to build.**
+
+[rubyeverywhere.com](https://rubyeverywhere.com) · by [Andrea Fomera](https://afomera.dev)
+
+RubyEverywhere takes a Rails (or Sinatra, or Hanami) app and gives it a native
+life on the platforms your users are already on:
+
+- **Desktop** — a [Tauri](https://tauri.app)-based shell. In *local* mode your
+  whole app is pressed into a single-file binary with
+  [Tebako](https://github.com/tamatebako/tebako) and runs on-device, no Ruby
+  install required; in *remote* mode the shell is a thin native wrapper around
+  your deployed app.
+- **iOS** — a [Hotwire Native](https://native.hotwired.dev) shell with a real
+  tab bar, nav-bar buttons, menus, action sheets, notifications, haptics,
+  biometrics, deep links, and native sign-in.
+- **Android** — a feature-for-feature Hotwire Native Android port of the same
+  shell, stamped from the same `config/everywhere.yml`.
+
+One config file, one CLI, one JavaScript API. The web app stays the source of
+truth — most of what you'd normally rebuild natively (tabs, routes, menus,
+badges) deploys with your Rails app rather than through an app-store review.
+
+## Install
+
+```sh
+gem install ruby_everywhere
+```
+
+This gives you two equivalent executables — `every` and `rbe` — plus the
+packaging toolchain (the `rbe-tebako` fork) as a dependency.
+
+Or add it to your app's Gemfile, which also wires up the Rails engine (bridge
+asset serving, importmap pin, view helpers, the live mobile config endpoint):
+
+```ruby
+gem "ruby_everywhere"
+```
+
+Requires Ruby >= 3.2.
+
+**The gem is free, and it always will be.** Everything here — the CLI, the
+desktop shell, both mobile shells, the bridge — is MIT licensed and yours to
+use, forever, with no account and no key. Local builds run on a Mac today
+(pressing, code signing, Xcode and the Android SDK all want a macOS host).
+If you don't own one, or you'd rather not keep a build toolchain healthy, the
+[RubyEverywhere Platform](https://rubyeverywhere.com) is a paid service coming
+soon that runs the exact same builds for you — see
+[Hosted builds](#hosted-builds) below. It's a convenience, never a gate: nothing
+in this gem is held back for it.
+
+## Quick start
+
+```sh
+cd path/to/your/app
+
+every install          # remote mode: a native shell around your deployed app
+every install --local  # local mode: compile and ship the app itself
+
+every doctor           # check the toolchain before your first build
+
+every dev              # dev server + native shells on demand, live reload
+every dev --ios        # ...straight into the iOS Simulator
+every dev --android    # ...straight into the Android emulator
+every dev --mobile     # ...both at once, built in parallel
+
+every build            # package the macOS .app
+every build --ios      # build the iOS shell
+every build --android  # build the APK/AAB
+```
+
+`every install` is idempotent — it adds `config/everywhere.yml`, a boot stub,
+and the framework-specific config tweaks it needs, and skips anything already
+in place. For Rails it does the surgery for you; for Sinatra and Hanami it
+vendors the bridge and prints the remaining wiring rather than guessing at your
+boot files.
+
+`every dev` never packages anything: it runs your ordinary dev server and points
+the native shells at it, so the edit-refresh loop is untouched Rails.
+
+It keeps a dock pinned to the bottom of the terminal showing what each target is
+doing, while the logs scroll normally above it — ordinary scrollback, so you can
+still scroll up and search a backtrace:
+
+```
+web  │ Started GET "/notes" for 127.0.0.1
+ios  │ ▸ compiling Swift sources
+────────────────────────────────────────────────────────────────
+● web :3000   ○ desktop   ⠙ iOS 42s   ✗ Android see dist/android-build.log
+⌨ d desktop · i iOS · a Android · b browser · l logs · r restart · ? help · q quit
+```
+
+Every target runs on its own thread, so builds happen in parallel and the keys
+keep working while one is going. A build that fails marks that target red and
+leaves everything else — the dev server included — running; fix the error and
+press the key again. `r` restarts just the dev server, `?` expands the full key
+list, and each line is tagged with the source that printed it once more than one
+thing is talking.
+
+Set `EVERY_NO_DOCK=1` (or pipe the output anywhere) to get plain, unadorned
+lines instead.
+
+## Configuration
+
+Everything per-app lives in `config/everywhere.yml`. The native shell templates
+are frozen — the CLI stamps a copy per app and only ever writes the identity,
+config, icon, and color files, so a shell upgrade never collides with your app.
+
+```yaml
+app:
+  name: My Really Awesome App
+  bundle_id: com.example.myapp     # set it once; renaming moves users' data
+  version: 1.2.0
+  entry_path: /dashboard           # where the app opens
+  icon: icon.png
+
+appearance:
+  tint_color: "#CC342D"
+  background_color:                # one hex string, or split by system theme
+    light: "#FAF9F7"
+    dark: "#1C1B1A"
+
+remote:
+  url: https://app.example.com     # remote mode: the deployed app to wrap
+
+window:                            # desktop window chrome
+  title_bar: overlay               # decorated (default) | overlay | frameless
+  title: false                     # draw the title text
+  size: [1100, 750]
+  min_size: [600, 400]
+  drag_height: 28                  # top strip that drags the window; 0 to opt out
+
+tabs:                              # the native mobile tab bar
+  - name: Builds
+    path: /builds
+    icons:
+      ios: hammer                  # SF Symbol
+      android: build               # Material icon
+
+permissions:                       # only declared permissions can ever prompt
+  notifications: true
+  camera: "Scan QR codes to pair devices."   # the sentence iOS shows
+
+rules:                             # Hotwire Native path configuration
+  - patterns: ["/preferences$"]
+    properties:
+      context: modal
+
+native:                            # code compiled into the native shells
+  desktop:
+    commands: [scan_ports]         # Rust in native/desktop/, callable from the page
+    crates:
+      serialport: "4.3"
+
+build:
+  ruby: "4.0.6"
+  targets: [macos-arm64, ios-arm64, android-arm64]
+
+updates:                           # self-hosted, signed auto-updates
+  url: https://updates.example.com
+  public_key: RWQ…
+  auto: check                      # off | check | download | install
+```
+
+Also supported: `auth:` (native OAuth sign-in with a callback scheme),
+`deep_linking:` (universal links / App Links — the gem serves the
+`apple-app-site-association` and `assetlinks.json` files for you), and
+`native:` for "supernative" extensions — Swift you keep in your app repo under
+`native/ios/` that `every build` compiles into the shell, including SwiftUI
+screens, bridge components, a custom splash, and pinned SPM packages.
+
+Desktop has the same seam in `native/desktop/`, shaped for what a desktop app
+actually wants: not native screens (the whole UI is a webview) but the machine
+underneath it. Drop in Rust, pin the crates you need, and call it from the page:
+
+```yaml
+native:
+  desktop:
+    commands: [scan_ports]
+    setup: true              # run native/desktop/setup.rs at boot
+    crates:
+      serialport: "4.3"
+```
+
+```rust
+// native/desktop/serial.rs
+pub fn scan_ports(_app: &tauri::AppHandle, payload: serde_json::Value)
+    -> Result<serde_json::Value, String> { … }
+```
+
+```js
+const ports = await Everywhere.desktop.invoke("scan_ports", { baud: 9600 })
+```
+
+Declaring anything under `native.desktop` has a real cost the mobile sections
+don't: the desktop shell stops being one prebuilt binary shared by every app and
+gets compiled per app, so the first build takes minutes instead of seconds. Apps
+that declare nothing are untouched.
+
+Images the desktop shell itself draws live in `native/desktop/assets/`, using the
+same `<name>[@2x|@3x][~dark].png` filenames the mobile assets folders use.
+Name one `tray` (or `tray-template` for a macOS template image) and it becomes
+the menu-bar icon; a custom `splash:` can reference the rest as
+`assets/logo.png`. These are for the shell, not your pages — images your HTML
+references should keep coming from the asset pipeline.
+
+`window:` shapes the desktop frame. `title_bar: overlay` is the macOS look where
+the traffic lights float over your page and there's no title text — pair it with
+the `.everywhere-titlebar-inset` class from `everywhere/native.css`, which
+reserves exactly the space they sit in. `frameless` removes the system chrome
+altogether; the page then draws its own bar and drives the buttons through
+`Everywhere.window`. Windows and Linux have no overlay style, so `overlay`
+behaves as `frameless` there.
+
+Either way the window stays draggable with no markup: the shell makes the top
+28px of the page drag it (and double-click zoom it), while buttons and links up
+there keep their clicks. `window.drag_height: 0` hands that back to you.
+
+Tabs and path rules ship two ways from that one source: baked into the app
+bundle for offline/first launch, and served live from
+`/everywhere/{ios,android}_v1.json`, so changing them deploys with your web app.
+`Everywhere.filter_tabs` lets you vary the tab bar per request — it shares the
+app's session, so signed-out users can get a different bar without a release.
+
+## The JavaScript bridge
+
+The gem ships `@rubyeverywhere/bridge` — one API for the browser, the desktop
+shell, and the mobile shells. Rails apps get it served and importmap-pinned
+automatically; Sinatra and Hanami get it vendored to `public/bridge.js`.
+
+```js
+import Everywhere from "@rubyeverywhere/bridge"
+
+Everywhere.platform          // "desktop" | "mobile" | "browser"
+Everywhere.native            // true inside a RubyEverywhere app
+
+Everywhere.notify({ title, body })
+Everywhere.menu({ title, items })
+Everywhere.haptics.impact("medium")
+Everywhere.badge.setTab("/inbox", 3)
+Everywhere.permissions.request("camera")
+Everywhere.storage.set("theme", "dark")
+Everywhere.updates.check()
+Everywhere.window.close()    // desktop, for a page-drawn title bar
+```
+
+Everything degrades gracefully — the same page works in a plain browser tab and
+gains native powers inside the app. See
+[`bridge/README.md`](bridge/README.md) for the full surface.
+
+Most native chrome needs no JavaScript at all. Tag ordinary markup and the
+bridge lifts it into real native controls; tapping the native control just
+`.click()`s the element it mirrors, so behavior stays defined once in the DOM.
+Rails ships helpers that emit exactly that markup:
+
+```erb
+<%= everywhere_nav_button "New", new_note_path, icons: { ios: "plus", android: "add" } %>
+<%= everywhere_fab new_note_path %>
+<%= everywhere_nav_menu "More" do %>
+  <%= everywhere_menu_item "Delete", note_path(@note), method: :delete, style: "destructive" %>
+<% end %>
+```
+
+Plus `native_app?`, `native_platform`, `everywhere_badge`,
+`everywhere_biometric_lock`, and friends.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `every install` | Prepare an app (boot stub, `config/everywhere.yml`, config tweaks) |
+| `every doctor` | Check the toolchain — Tebako, Rust, brew deps, Xcode, Android SDK/JDK |
+| `every dev` | Dev server with native shells on demand (`--desktop --ios --android --mobile --browser`) |
+| `every logs` | Stream shell logs from the Simulator or Android device |
+| `every build` | Package natively — desktop, `--ios`, or `--android` |
+| `every icon` | Generate `.icns` / `.ico` / Linux icons from a source PNG |
+| `every release` | Sign, notarize, staple, and emit a `release.json` receipt |
+| `every updates keygen` | Generate a minisign-compatible update-signing keypair |
+| `every publish` | Publish a release to your update bucket |
+| `every clean` | Remove the shell build caches |
+| `every shell-dir` | Print the path of the bundled shell template |
+| `every platform …` | Hosted builds: `login`, `logout`, `auth status`, `build` |
+
+Run `every` with no arguments for the full list, or `every <command> --help` for
+a command's flags.
+
+## Auto-updates
+
+Desktop releases can update themselves from a bucket you own, with no service in
+the middle:
+
+```sh
+every updates keygen                  # once, per app
+every release                         # build, sign, notarize, staple
+every publish --notes-file NOTES.md   # sign the manifest, upload, flip latest.json
+```
+
+The public key ships in the app; the secret key never leaves your machine. Apps
+can check, install, and switch channels at runtime via `Everywhere.updates`.
+
+## Hosted builds
+
+Don't have a Mac, or want iOS and Android built without babysitting Xcode, the
+Android SDK, and a signing setup? The **RubyEverywhere Platform** — a paid
+service, coming soon — runs the same builds on managed machines and hands back
+the artifacts. The CLI already speaks to it:
+
+```sh
+every platform login
+every platform build --target ios-arm64,android-arm64
+```
+
+Same gem, same `config/everywhere.yml`, same output — you're paying for the
+build machines and the toolchain upkeep, not for features. The gem stays free
+and complete on its own.
+
+## Project layout
+
+```
+lib/everywhere/          the CLI, config, builders, and Rails engine
+exe/every, exe/rbe       the executables
+bridge/                  @rubyeverywhere/bridge — the JS half
+support/desktop/         the Tauri desktop shell template
+support/mobile/ios/      the Hotwire Native iOS shell template
+support/mobile/android/  the Hotwire Native Android shell template
+```
+
+The shell templates have their own READMEs documenting the freeze rules — what
+the CLI stamps per app and what it must never touch:
+[iOS](support/mobile/ios/README.md) · [Android](support/mobile/android/README.md).
+
+## Contributing
+
+Bug reports and pull requests are welcome. Run the test suite with `rake test`.
+
+## License
+
+Released under the [MIT License](LICENSE.txt). Copyright © 2026 Andrea Fomera.

data/bridge/README.md

@@ -135,6 +135,75 @@ tap, and `<meta name="everywhere:badge">` / `<meta name="everywhere:tab-badge">`
 tags (the `everywhere_badge` / `everywhere_tab_badge` Rails helpers) are
 applied on every Turbo visit.
 
+### Desktop extensions
+
+Rust the app keeps in `native/desktop/` and declares under
+`native.desktop.commands` in `everywhere.yml`:
+
+```js
+Everywhere.desktop.supported          // true in the desktop shell
+
+const ports = await Everywhere.desktop.invoke("scan_ports", { baud: 9600 })
+```
+
+The payload arrives in Rust as a `serde_json::Value` and whatever the command
+returns comes back as the resolved value; a command that returns `Err` rejects
+with its own message.
+
+Unlike the rest of the bridge this does **not** degrade — there's no web
+equivalent for "talk to a serial port", so off the desktop it rejects rather
+than resolving something untrue. Gate on `Everywhere.desktop.supported`.
+
+Under the hood this is an event round-trip, not Tauri's `invoke`: a
+RubyEverywhere page is always served over http, and Tauri v2 refuses `invoke`
+from any http origin — including the packaged app's own localhost server.
+
+### Window controls
+
+Desktop apps that draw their own title bar — `window.title_bar: overlay` or
+`frameless` in `everywhere.yml` — drive the window from the page:
+
+```js
+Everywhere.window.supported           // true in the desktop shell
+
+Everywhere.window.minimize()
+Everywhere.window.maximize()
+Everywhere.window.unmaximize()
+Everywhere.window.toggleMaximize()    // what a title-bar double-click does
+Everywhere.window.close()
+await Everywhere.window.isMaximized() // Promise<boolean>
+Everywhere.window.startDragging()     // from a pointerdown on a custom bar
+```
+
+`overlay` keeps the macOS traffic lights and only hides the title, so the page
+just needs to stay clear of them; `frameless` removes every control, so the page
+supplies its own.
+
+**Dragging works out of the box.** With no system title bar left to grab, the
+shell makes the top 28px of the page drag the window, and double-click there
+zooms it — no markup required. Buttons, links and inputs in that strip keep
+their clicks:
+
+```html
+<header class="everywhere-titlebar">
+  <span>My App</span>
+  <button onclick="Everywhere.window.close()">×</button>
+</header>
+```
+
+To make something *outside* the strip draggable, mark it
+`data-tauri-drag-region`. To own dragging yourself, set `window.drag_height: 0`
+in `everywhere.yml` and call `startDragging()` from your own handlers.
+
+`everywhere/native.css` ships `.everywhere-titlebar` (a drag strip that clears
+the traffic lights in overlay mode) plus `.everywhere-titlebar-inset` and
+`.everywhere-titlebar-controls-inset` padding utilities. They key off an
+attribute the bridge stamps on `<html>`, so they're inert in a browser tab, on
+mobile, and in a normal decorated window.
+
+Everything here resolves to `null` off the desktop, so the same markup is safe
+everywhere.
+
 ### Auto-updates
 
 Inside the desktop shell, apps with an update feed configured can check,
@@ -164,7 +233,7 @@ In a plain browser tab the updates API is inert: `check()` resolves
 ## Platforms
 
 - **desktop** — the Tauri-based RubyEverywhere shell. Notifications, dialogs,
-  clipboard, shell events, and auto-updates are native.
+  clipboard, shell events, window controls, and auto-updates are native.
 - **browser** — honest web fallbacks: the Notification API, `window.confirm`,
   `navigator.clipboard`, DOM CustomEvents.
 - **mobile** — Hotwire Native (iOS shell). `notify()` delivers a native local