ruby_everywhere 0.4.0 → 0.6.0

data/lib/everywhere/shellout.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "ui"
+require_relative "console"
+require_relative "child_processes"
 
 module Everywhere
   # All external commands (tebako, cargo, the app's own bin/dev) run outside
@@ -8,27 +10,57 @@ module Everywhere
   module Shellout
     module_function
 
-    def unbundled(&block)
-      defined?(Bundler) ? Bundler.with_unbundled_env(&block) : yield
+    # The environment a child should get: this gem's bundle stripped back out,
+    # plus the caller's overrides.
+    #
+    # This is handed to spawn as its env argument rather than swapped into ENV,
+    # which is what Bundler.with_unbundled_env does (ENV.replace, twice, around
+    # the block). That is process-global mutable state, and `every dev` now runs
+    # the iOS and Android builds concurrently: two overlapping swaps race so that
+    # one child inherits the CLI's bundle after all — the exact thing unbundling
+    # exists to prevent — and ENV is left wrong for the rest of the session.
+    #
+    # A nil value tells spawn to REMOVE that key, which is most of what
+    # unbundling is. The resulting child environment is identical to what
+    # with_unbundled_env produced, since Bundler.unbundled_env is derived from
+    # the snapshot taken before Bundler was activated either way.
+    def child_env(overrides = {})
+      base = unbundled_base
+      delta = {}
+      ENV.each_key { |key| delta[key] = nil unless base.key?(key) }
+      base.each { |key, value| delta[key] = value unless ENV[key] == value }
+      delta.merge(overrides.transform_keys(&:to_s))
+    end
+
+    # Bundler.unbundled_env derives from `original_env`, a snapshot frozen at
+    # load time, so this is genuinely constant for the life of the process.
+    def unbundled_base
+      @unbundled_base ||= defined?(Bundler) ? Bundler.unbundled_env : ENV.to_h
     end
 
     def run!(env, *cmd, chdir: Dir.pwd)
-      success = unbundled { system(env, *cmd, chdir: chdir) }
+      success = system(child_env(env), *cmd, chdir: chdir)
       UI.die!("command failed: #{cmd.join(" ")}") unless success
     end
 
+    # quiet also detaches stdin. A quiet command is by definition one that has
+    # nothing to say to the terminal, and `every dev` reads single keystrokes
+    # from that same terminal — a child left holding stdin silently eats the
+    # keypresses the menu is waiting on.
     def run?(*cmd, chdir: Dir.pwd, quiet: false)
       opts = { chdir: chdir }
-      opts.update(out: File::NULL, err: File::NULL) if quiet
-      unbundled { system(*cmd, **opts) }
+      opts.update(in: File::NULL, out: File::NULL, err: File::NULL) if quiet
+      system(child_env, *cmd, **opts)
     end
 
     # Run a command and capture its combined stdout+stderr. Returns
     # [output_string, Process::Status]. For probing tool output (codesign,
-    # stapler, notarytool) rather than driving a build.
+    # stapler, notarytool) rather than driving a build. A leading Hash is env
+    # overrides, matching Open3's own convention.
     def capture(*cmd)
       require "open3"
-      unbundled { Open3.capture2e(*cmd) }
+      overrides = cmd.first.is_a?(Hash) ? cmd.shift : {}
+      Open3.capture2e(child_env(overrides), *cmd)
     rescue Errno::ENOENT
       ["", nil]
     end
@@ -40,18 +72,32 @@ module Everywhere
     # prettify what a human sees; the on-disk log always gets the raw stream, so
     # nothing is lost. Unrecognized lines (filter returns nil) are shown dimmed
     # and indented so they read as background detail under the current step.
+    #
+    # The signature is deliberately unchanged: the builder tests stub this with
+    # fixed-signature lambdas, and cancellation is wired up out of band through
+    # ChildProcesses instead.
     def run_logged!(env, cmd, log:, filter: nil)
       require "open3"
       success = false
-      unbundled do
-        File.open(log, "w") do |logf|
-          Open3.popen2e(env, *cmd) do |stdin, out, wait|
-            stdin.close
+      File.open(log, "w") do |logf|
+        # Inside an `every dev` worker the build leads its own process group,
+        # for two reasons: a Ctrl-C at the terminal no longer reaches
+        # xcodebuild/gradlew behind the CLI's back (the CLI decides when a build
+        # dies), and teardown can TERM the whole compile tree with one signal.
+        # Outside dev this stays off, so Ctrl-C during `every build` still stops
+        # the compiler as it always has.
+        opts = ChildProcesses.isolated? ? { pgroup: true } : {}
+        Open3.popen2e(child_env(env), *cmd, **opts) do |stdin, out, wait|
+          stdin.close
+          ChildProcesses.track(wait.pid)
+          begin
             out.each_line do |raw|
               logf.write(raw)
               emit(raw, filter)
             end
             success = wait.value.success?
+          ensure
+            ChildProcesses.untrack(wait.pid)
           end
         end
       end
@@ -61,13 +107,13 @@ module Everywhere
     # Route one raw line to the console: verbatim when there's no filter, else
     # the filter's rendition (:drop swallows it, nil falls back to dim detail).
     def emit(raw, filter)
-      return $stdout.print(raw) unless filter
+      return Console.print(raw) unless filter
 
       shown = filter.call(raw)
       case shown
       when :drop, false then nil
-      when nil          then $stdout.puts("    #{UI.gray(UI.short_path(raw.rstrip))}")
-      else                   $stdout.puts(shown)
+      when nil          then Console.puts("    #{UI.gray(UI.short_path(raw.rstrip))}")
+      else                   Console.puts(shown)
       end
     end
     private_class_method :emit
@@ -75,7 +121,36 @@ module Everywhere
     # pgroup: the child leads its own process group so teardown can TERM the
     # whole tree (foreman + watchers) without signalling the CLI itself.
     def spawn(env, cmd, chdir:)
-      unbundled { Process.spawn(env, cmd, chdir: chdir, pgroup: true) }
+      Process.spawn(child_env(env), cmd, chdir: chdir, pgroup: true)
+    end
+
+    # Same, but on a pseudo-terminal, returning [master_io, pid].
+    #
+    # `every dev` relays the dev server's and desktop shell's output itself so
+    # it can tag each line with its source and keep the dock pinned at the
+    # bottom. A plain pipe would work, but the children would see a non-TTY and
+    # foreman, cargo and friends would drop their colors and progress output; on
+    # a pty they behave exactly as they do when you run them by hand.
+    #
+    # PTY.spawn calls setsid, so the child leads its own session: a terminal
+    # SIGINT can't reach it, and Process.kill("TERM", -pid) still takes down the
+    # whole tree.
+    def spawn_pty(env, cmd, chdir:)
+      require "pty"
+      # PTY.spawn hands back the read and write ends of the pty MASTER. We never
+      # forward stdin, so the write end is closed immediately — the child keeps
+      # running because the read end still holds the master open.
+      reader, writer, pid = PTY.spawn(child_env(env), cmd, chdir: chdir)
+      writer.close
+      [reader, pid]
+    end
+
+    # PTY is POSIX-only. Callers fall back to spawn + inherited fds.
+    def pty?
+      require "pty"
+      true
+    rescue LoadError
+      false
     end
   end
 end

data/lib/everywhere/task_pool.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "console"
+require_relative "child_processes"
+
+module Everywhere
+  # Named background tasks for the `every dev` key loop.
+  #
+  # Three guarantees, each of which fixes a specific way the old synchronous
+  # command misbehaved:
+  #
+  #   * At most one live task per name. Pressing `i` twice must not run two
+  #     iOS builds over the same staged work dir, which Builders::Ios rm_rf's
+  #     and re-copies on every run.
+  #   * No task failure can reach the main thread. A Swift compile error used to
+  #     unwind through the key loop into Dev#call's `ensure teardown` and take
+  #     the Rails server down with it.
+  #   * Every task is cancellable. Its children lead their own process groups
+  #     and are TERMed (then KILLed) at shutdown.
+  class TaskPool
+    # A task's failure is data, not control flow — hence `rescue Exception`, one
+    # of the few places it is the correct choice. MRI enqueues a SystemExit that
+    # escapes a non-main thread onto the MAIN thread and re-raises it there,
+    # wherever that thread happens to be. Since UI.die! raises Everywhere::Fatal
+    # (a SystemExit), `rescue StandardError` here would leave the original bug
+    # fully intact, just relocated. Verified:
+    #
+    #   ruby -e 'Thread.new { raise SystemExit.new(2) }; sleep 1; puts "alive"'
+    #   # => exits 2, never prints
+    GRACE = 5
+
+    def initialize(on_error: nil)
+      @lock = Mutex.new
+      @threads = {}
+      @failed = []
+      @stopping = false
+      @on_error = on_error
+    end
+
+    # :started, :busy or :stopping.
+    def start(name, &block)
+      @lock.synchronize do
+        return :stopping if @stopping
+        return :busy if @threads[name]&.alive?
+
+        @threads[name] = spawn_worker(name, &block)
+        retag
+        :started
+      end
+    end
+
+    def busy?(name) = @lock.synchronize { !!@threads[name]&.alive? }
+
+    def failed = @lock.synchronize { @failed.dup }
+
+    def any_running? = @lock.synchronize { @threads.each_value.any?(&:alive?) }
+
+    # Join every live task. Used by the headless path, where there is no key
+    # loop to keep the process alive and a failed build still has to be news.
+    def wait_all
+      loop do
+        live = @lock.synchronize { @threads.each_value.select(&:alive?) }
+        break if live.empty?
+
+        live.each(&:join)
+      end
+      Console.multiplexed = false
+    end
+
+    # Kill the tasks' children first, then the threads. Ordering matters: a
+    # worker blocked reading a build's output only unwinds once that build is
+    # gone, so signalling the children is what actually makes the joins return.
+    def shutdown(grace: GRACE)
+      live = @lock.synchronize do
+        @stopping = true
+        @threads.each_value.select(&:alive?)
+      end
+      return if live.empty?
+
+      live.each { |thread| ChildProcesses.terminate(thread, grace: grace) }
+      deadline = now + grace
+      live.each { |thread| thread.join([deadline - now, 0].max) }
+      live.select(&:alive?).each(&:kill)
+      Console.multiplexed = false
+    end
+
+    private
+
+    # Called while holding @lock; the new thread also takes @lock in its ensure.
+    # That is not a deadlock — the worker simply blocks until start returns —
+    # but it is why these two must not be collapsed into one synchronize block.
+    def spawn_worker(name, &block)
+      Thread.new do
+        # Set from inside the thread, as its first statement: assigning it after
+        # Thread.new returns races a task that fails immediately.
+        Thread.current.name = name.to_s
+        Thread.current.report_on_exception = false
+        Console.tag = name
+        ChildProcesses.isolate!
+
+        begin
+          block.call
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          stopping = @lock.synchronize { @failed << name; @stopping }
+          @on_error&.call(name, e, stopping)
+        ensure
+          @lock.synchronize { retag }
+        end
+      end
+    end
+
+    # Tag output by source only while two or more tasks are live: with one build
+    # running, the output is exactly what it has always been. Thread.current is
+    # excluded because a worker calling this from its own ensure is still
+    # #alive? and would keep tagging on for the task that just finished.
+    def retag
+      live = @threads.each_value.count { |t| t.alive? && t != Thread.current }
+      Console.multiplexed = live > 1
+    end
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/everywhere/ui.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "fatal"
+require_relative "console"
+
 module Everywhere
   # Terminal output helpers. Colors follow the informal standard:
   # on when stdout is a TTY or CLICOLOR_FORCE=1, always off when NO_COLOR is set.
@@ -69,14 +72,18 @@ module Everywhere
     def warn_line(msg)    = "#{yellow("!")} #{msg}"
     def success_line(msg) = "#{green("✓")} #{bold(msg)}"
 
-    def phase(msg)   = puts(phase_line(msg))
-    def step(msg)    = puts(step_line(msg))
-    def substep(msg) = puts(substep_line(msg))
-    def detail(msg)  = puts(detail_line(msg))
-    def ok(msg)      = puts(ok_line(msg))
-    def bad(msg)     = puts(bad_line(msg))
-    def warn(msg)    = puts(warn_line(msg))
-    def success(msg) = puts(success_line(msg))
+    # Everything prints through Console, which serializes concurrent writers and
+    # gives the `every dev` dock a chance to repaint around each line. With no
+    # dock installed it is a plain $stdout.write, resolved per call so
+    # capture_io still works.
+    def phase(msg)   = Console.puts(phase_line(msg))
+    def step(msg)    = Console.puts(step_line(msg))
+    def substep(msg) = Console.puts(substep_line(msg))
+    def detail(msg)  = Console.puts(detail_line(msg))
+    def ok(msg)      = Console.puts(ok_line(msg))
+    def bad(msg)     = Console.puts(bad_line(msg))
+    def warn(msg)    = Console.puts(warn_line(msg))
+    def success(msg) = Console.puts(success_line(msg))
 
     # An indented, dim outcome under a substep — e.g. "accepted", "valid on disk".
     def note_line(msg, marker: "·", color: :gray)
@@ -84,15 +91,28 @@ module Everywhere
       "    #{tint.call(marker)} #{tint.call(msg)}"
     end
 
-    def note(msg, marker: "·", color: :gray) = puts(note_line(msg, marker: marker, color: color))
+    def note(msg, marker: "·", color: :gray) = Console.puts(note_line(msg, marker: marker, color: color))
 
+    # Ends the current unit of work. At the top level Ruby exits 1 and prints
+    # nothing extra, so this behaves exactly like the Kernel#abort it replaced —
+    # but inside `every dev` the worker thread running the build catches the
+    # Fatal, marks that target failed, and hands you back the key menu with the
+    # dev server still serving. The message is the same string abort received,
+    # so every assert_raises(SystemExit) reading err.message is unaffected.
     def die!(msg)
-      abort "#{red("✗")} #{red(msg)}"
+      line = "#{red("✗")} #{red(msg)}"
+      Console.error(line)
+      raise Everywhere::Fatal.new(1, line)
     end
 
     # A yes/no fact, colored by truthiness (for signing receipts).
     def yn(bool) = bool ? green("yes") : red("no")
 
+    # Braille spinner frames, shared by the transient Status line and the
+    # `every dev` dock. Ten frames at ~200ms is one revolution every two
+    # seconds — legible as motion without being distracting.
+    FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
     # --- transient status line -------------------------------------------------
 
     # A single self-rewriting line for waits that produce no output — chiefly
@@ -104,8 +124,12 @@ module Everywhere
     # line every HEADLESS_INTERVAL seconds. Callers MUST `clear` before writing
     # anything else — `update` tracks whether a line is currently on screen so
     # `clear` is cheap and idempotent.
+    #
+    # NOTE: this writes to its `io:` directly, NOT through Console, so it is not
+    # serialized against other writers. That's fine for its one caller
+    # (`every platform build`, single-threaded) — do not reuse it concurrently.
     class Status
-      FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+      FRAMES = UI::FRAMES
       HEADLESS_INTERVAL = 30 # seconds between plain lines when not a TTY
 
       def initialize(io: $stdout)
@@ -157,6 +181,25 @@ module Everywhere
       "#{secs / 3600}h #{(secs % 3600) / 60}m"
     end
 
+    # --- ANSI ------------------------------------------------------------------
+
+    # Escape sequences a tool writes when it thinks it's on a terminal — which,
+    # since `every dev` relays its children over a pty, they all do. Two forms
+    # matter in practice: SGR color (CSI), and OSC-8 hyperlinks, which cargo
+    # wraps around the profile name in its own status lines.
+    ANSI = /
+      \e\][^\a\e]*(?:\a|\e\\)     # OSC ... terminated by BEL or ST
+      |
+      \e\[[0-9;?]*[ -\/]*[@-~]    # CSI ... final byte
+      |
+      \e[@-Z\\-_]                 # two-character escapes
+    /x
+
+    # For MATCHING, never for display: a filter that pattern-matches colored
+    # output has to look past the codes, but the colors are still what the
+    # developer wants to read.
+    def strip_ansi(str) = str.to_s.gsub(ANSI, "")
+
     # --- path shortening ------------------------------------------------------
 
     # Collapse the noisy machine paths that external tools echo (codesign,

data/lib/everywhere/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Everywhere
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 
   # Version of the @rubyeverywhere/bridge JS this gem ships. bridge/ in the
   # gem IS the npm package (served to Rails apps by Everywhere::Engine,

data/support/agents/AGENTS.md

@@ -0,0 +1,90 @@
+## RubyEverywhere
+
+This is a {{FRAMEWORK}} app that also ships as a native desktop and mobile app, via the
+[`ruby_everywhere`](https://rubyeverywhere.com) gem. The desktop shell is Tauri, the mobile
+shells are Hotwire Native, and all three are driven from one config file
+(`config/everywhere.yml`), one CLI (`every`, aliased `rbe`), and one JavaScript API
+(`Everywhere`) with server-side helpers to match.
+
+**The web app is the source of truth.** You do not edit the shells — you edit the app, its
+views, and the config. Full docs: <https://rubyeverywhere.com/docs>.
+
+### How this app reaches its users: {{MODE}} mode
+
+{{MODE_NOTES}}
+
+{{FRAMEWORK_VIEWS}}
+
+### config/everywhere.yml
+
+Everything native is declared here: tabs, path rules, permissions, window chrome, menus,
+tray items, colors, deep links, auto-updates. Top-level keys: `app`, `remote`, `appearance`,
+`tabs`, `rules`, `permissions`, `menu`, `tray`, `window`, `native`, `auth`, `deep_linking`,
+`build`, `updates`, `platforms`. Full reference:
+<https://rubyeverywhere.com/docs/shared/everywhere-yml>.
+
+Things that bite:
+
+- **`app.bundle_id` is identity, not cosmetics.** It names the app-data directory on every
+  platform (and the macOS bundle id). Renaming it orphans users' local data and settings.
+- **Permissions gate everything on mobile.** A permission that isn't declared under
+  `permissions:` resolves to `undeclared` and never prompts. `camera` and `location` must carry
+  the sentence iOS shows when asking, or the build fails.
+- **`tabs:` and `rules:` deploy with the web app.** They're baked into the bundle *and* served
+  live from `/everywhere/ios_v1.json` and `/everywhere/android_v1.json`, so changing a tab or a
+  presentation rule ships with your next deploy — no app-store release.
+- Most other keys (`window`, `menu`, `tray`, `permissions`, `appearance`) are read at build
+  time and do need a new build.
+
+### The JavaScript bridge
+
+One API across browser, desktop, and mobile. It degrades gracefully in a plain browser, so
+you can call it unconditionally.
+
+```js
+import Everywhere from "@rubyeverywhere/bridge"
+window.Everywhere = Everywhere
+```
+
+Surface: `platform` (`"desktop" | "mobile" | "browser"`), `os`, `native`, `version`,
+`notify()`, `confirm()`, `on()`, `visit()`, `menu()`, `reloadTabs()`, `resetApp()`, and the
+namespaces `auth`, `clipboard`, `haptics`, `permissions`, `biometrics`, `instance`, `storage`,
+`badge`, `desktop` (`desktop.invoke`), `window` (`minimize`/`maximize`/`close`/`startDragging`/…),
+and `updates` (`check`/`install`/`setChannel`/`on`).
+
+Reach for the bridge when something has to happen in response to JS. For anything you can
+render, prefer the markup above — it's CSP-safe, correct on first paint, and works in a
+browser without a code path of its own.
+
+### Commands
+
+Run these from the app root.
+
+| Command | What it does |
+| --- | --- |
+| `every dev` | Dev server plus native shells on demand, live reload (`--desktop --ios --android --mobile --browser`) |
+| `every doctor` | Check the toolchain before a first build |
+| `every build` | Build the native shells — desktop, or `--ios` / `--android` |
+| `every logs` | Stream shell logs from the iOS Simulator or an Android device |
+| `every icon` | Generate `.icns` / `.ico` / Linux icons from a source PNG |
+| `every release` | Sign, notarize, staple, and emit `dist/release.json` |
+| `every publish` | Publish a release to the app's update bucket |
+| `every clean` | Remove the shell build caches |
+
+`every dev` never packages anything — it runs the ordinary dev server and points the shells
+at it, so the edit-refresh loop is unchanged.
+
+Two directories are build output, never source: `dist/` (artifacts) and `~/.rubyeverywhere`
+(stamped shell projects and caches). Don't commit them, don't hand-edit them — the next build
+overwrites both.
+
+### Config `every install` touched
+
+These exist so this codebase can also be compiled and shipped on-device, and several of them
+look like mistakes if you don't know that. Leave them in place — full rationale at
+<https://rubyeverywhere.com/docs>.
+
+{{FRAMEWORK_NOTES}}
+
+Re-running `every install` is idempotent and skips anything already in place, so it's the
+right way to restore one of these if it goes missing.

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

@@ -0,0 +1,26 @@
+### 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`, served via `Rack::Static`, carries the styling helpers — including
+`.everywhere-titlebar-inset` for `window.title_bar: overlay`. Hanami's CSP forbids inline
+scripts, so every bit of this has to be attributes and external files; that's the same reason
+the markup contract exists in the first place.

data/support/agents/frameworks/hanami.md

@@ -0,0 +1,10 @@
+- `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`. Serve `public/` via `Rack::Static` and load `/bridge.js` as an **external**
+  module; Hanami's CSP forbids inline scripts.
+
+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: override `DATABASE_URL` from
+`ENV["NATIVE_STORAGE_DIR"]` in `config.ru` when `NATIVE_PACKAGED` is set, and migrate before
+Hanami finalizes (`Hanami.prepare`, run the ROM migrations, then `require "hanami/boot"`).
+Both only matter for on-device packaging.

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

@@ -0,0 +1,98 @@
+### Native chrome from your views
+
+`Everywhere::Engine` mixes a set of helpers into every view. **Prefer these over hand-written
+markup or JavaScript.** They render a real link or button that works in a browser, and carry
+the `data-everywhere-*` attributes the shell lifts into native chrome — tapping the native
+control just clicks the element it mirrors, so behavior is defined once and CSP is never an
+issue.
+
+Icons are per-platform, like tabs: `icon:` is the shared fallback, `icons: { ios:, android: }`
+names an SF Symbol and a Material Symbol respectively.
+
+**Where am I?** Pick the narrowest predicate that's true of what you're branching on.
+
+| Helper | |
+| --- | --- |
+| `native_app?` | any shell — iOS, Android, or desktop. "Not a browser tab." |
+| `mobile_app?` | a phone: safe-area insets, the native tab bar, biometrics, the OAuth handoff |
+| `desktop_app?` | the desktop window: title bar, menu bar, pointer |
+| `native_platform` | `:ios`, `:android`, `:desktop`, or `nil` in a browser |
+| `mobile_platform` | `:ios`, `:android`, or `nil` (including on desktop) |
+| `native_version` | the shell's version as a `Gem::Version` — gate features that need a newer shell |
+
+Detection is by User-Agent, so it's correct on the server before the JS bridge has booted.
+Hiding a web nav in favor of native chrome is usually `mobile_app?`, not `native_app?` — the
+desktop shell has no native navigation to replace it with.
+
+**Navigation bar.** Renders in the page for browsers; the shell hides the in-page copy and
+puts it in the top bar.
+
+```erb
+<%= everywhere_nav_button "New", new_note_path, icons: { ios: "plus", android: "add" } %>
+<%= everywhere_nav_button "Back", notes_path, side: "left" %>
+
+<%= form_with model: @note do |f| %>
+  <%= everywhere_submit_button "Save" %>   <%# mirrors the form's submit into the nav bar %>
+<% end %>
+
+<%= everywhere_nav_menu do %>              <%# ⋯ pull-down; a native UIMenu in the shell %>
+  <%= everywhere_menu_item "Share", share_path, icons: { ios: "square.and.arrow.up" } %>
+  <%= everywhere_menu_item "Delete", note_path(@note), method: :delete, style: "destructive" %>
+<% end %>
+```
+
+`everywhere_nav_button` takes `side:` (`"right"` / `"left"`), `style:` (`"done"`,
+`"destructive"`), and `type: :submit`. `everywhere_menu_item` is a link by default; `method:`
+makes it a Turbo method link, `type: :submit` with `form:` submits a form, and
+`style: "destructive"` tints it natively.
+
+**In-content controls.**
+
+```erb
+<%# floating action button — fixed, safe-area-aware, tap haptic in the shell %>
+<%= everywhere_fab new_note_path, icon: :plus, label: "New note" %>
+<%= everywhere_fab compose_path, icon: :pencil, label: "Compose", extended: true %>
+
+<%# action sheet: native sheet in the shell, inline menu in a browser %>
+<%= everywhere_menu "Options" do %>
+  <%= everywhere_menu_item "Edit", edit_post_path(@post) %>
+  <%= everywhere_menu_item "Delete", post_path(@post), method: :delete, style: "destructive" %>
+<% end %>
+```
+
+`everywhere_fab` accepts `icon:` (a built-in line glyph), `label:` (accessible name, plus a
+visible pill with `extended: true`), `side:`, and `haptic:` — or a block for custom content.
+
+**Badges.** Server-rendered meta tags the bridge applies on every Turbo visit; `0` clears.
+
+```erb
+<%= everywhere_badge Current.user.unread_count %>          <%# app icon %>
+<%= everywhere_tab_badge "/inbox", Current.user.unread_count %>  <%# a tab, by its everywhere.yml path %>
+```
+
+**Biometric gate.** Keeps sensitive markup hidden until Face ID / Touch ID passes, and only
+when the user has turned the device-local lock on. Browsers and the desktop shell render the
+content plainly. Needs `biometrics` under `permissions:` in `config/everywhere.yml`.
+
+```erb
+<%= everywhere_biometric_lock reason: "Unlock account settings" do %>
+  <%# profile, password, sessions… %>
+<% end %>
+
+<div data-everywhere-biometric-toggle-row hidden>
+  <label>Require Face ID <%= everywhere_biometric_toggle %></label>
+</div>
+```
+
+**Auth redirects.** In a controller, route post-sign-in redirects through the reset page so a
+phone shell rebuilds its web views and re-fetches its tab bar:
+
+```ruby
+redirect_to everywhere_auth_redirect(after_authentication_url)
+```
+
+**Tab bar, per request.** `Everywhere.filter_tabs { |tabs, request| … }` in an initializer
+varies the mobile tab bar — it shares the app's session; return `[]` to hide the bar.
+
+Styling helpers live in `everywhere/native.css`, including `.everywhere-titlebar-inset` for
+`window.title_bar: overlay`.

data/support/agents/frameworks/rails.md

@@ -0,0 +1,16 @@
+- `native_boot.rb` — the packaged-app entry point. Keep it thin and keep it at the app root.
+- `config/initializers/everywhere.rb` — packaged-only public-path and session-store setup.
+- `config/boot.rb` — bootsnap guarded with `unless ENV["NATIVE_PACKAGED"]` (its cache dir is
+  read-only when packaged).
+- `config/environments/production.rb` — `force_ssl` and `assume_ssl` are `false`, because a
+  packaged app's webview talks plain HTTP to `127.0.0.1`.
+- `config/puma.rb` — keep-alives off when packaged; WebKit reuses connections Puma has closed.
+- `config/database.yml` — the production SQLite path reads
+  `<%= ENV.fetch("NATIVE_STORAGE_DIR", "storage") %>`. Any database you add should use the same
+  lookup.
+- `app/javascript/application.js` — imports the bridge and exposes it as `window.Everywhere`.
+
+One rule that matters in every mode: the bridge is served and importmap-pinned by
+`Everywhere::Engine` straight from the gem, so it updates with `bundle update ruby_everywhere`.
+Don't vendor it into `vendor/javascript/` or pin it in `config/importmap.rb` — a local copy
+shadows the engine's and freezes the app on an old bridge.