ruby_everywhere 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ffb921df597efe047c25240e7d8b92aaad49c00c90d546020e053eac618739a
-  data.tar.gz: 17315b4c5d91eced13b44d7147942d7d6357ee791b8622425ab655eb97b1ab27
+  metadata.gz: 1c87aa5a2416d070a8047b790f28c7230882999b7df4f7f584256ee96852f066
+  data.tar.gz: 6fa25612acf17e6d90b3302a4e7f93a8d5ded79fd8ffb39aec318b908df32bcf
 SHA512:
-  metadata.gz: 71d9ba1ea63abe51a7262f02f069ef9f068d3192bb20800bdd0fba8bcd50f36f2daa83bb3f758e7273576b69b88be5541428b41f93021579cc1b5054532099ad
-  data.tar.gz: 59632bacae03ade28233832d0193d2500e4e3f85c07b7e61a39f1e086cc398b40f66d48091ffc9e336a11e2f91994b666ea60fc7ab2cbef2b76252d6fb0ada60
+  metadata.gz: 69fb1bdb659b8b886d9b602e09e21d8016caf140ac401ee371d4b0eaab2e06f3b342fb7742e2684570b80e71768fb2c5ede34dca3f1d5b9015185b93b176ba59
+  data.tar.gz: 450a804d3bf9765ea664e0728c66df31019e5633393680120ef9ec7ba40def7e69f163b9aaaf6b2d2fcec948e62c5d3821b26bb553924666dfb57b7d1c6b29cd

data/README.md

@@ -57,12 +57,14 @@ 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 install --agents # ...plus an AGENTS.md guide for AI coding agents
 
 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
@@ -75,9 +77,41 @@ 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.
 
+Working with an AI coding agent? `--agents` writes an `AGENTS.md` — the format
+Claude Code, Cursor, Copilot and Codex all read — covering the view helpers
+(`native_app?`, `everywhere_nav_button`, `everywhere_fab`, the menus and badges),
+`config/everywhere.yml`, the bridge API, and the `every` commands, so an agent
+reaches for the right helper instead of hand-rolling markup. It's framework- and
+mode-aware, and adds a one-line `CLAUDE.md` pointer if you don't already have
+one. If you already have an `AGENTS.md`, only the block between
+`<!-- rubyeverywhere:begin -->` and `<!-- rubyeverywhere:end -->` is written, so
+re-running refreshes our section and leaves your own notes alone.
+
 `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
@@ -101,6 +135,13 @@ appearance:
 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
@@ -117,6 +158,12 @@ rules:                             # Hotwire Native path configuration
     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]
@@ -134,6 +181,53 @@ Also supported: `auth:` (native OAuth sign-in with a callback scheme),
 `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.
@@ -159,6 +253,7 @@ 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
@@ -185,9 +280,9 @@ Plus `native_app?`, `native_platform`, `everywhere_badge`,
 
 | Command | What it does |
 | --- | --- |
-| `every install` | Prepare an app (boot stub, `config/everywhere.yml`, config tweaks) |
+| `every install` | Prepare an app (boot stub, `config/everywhere.yml`, config tweaks) — `--local`, `--agents` |
 | `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 --browser`) |
+| `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 |
@@ -237,9 +332,10 @@ and complete on its own.
 lib/everywhere/          the CLI, config, builders, and Rails engine
 exe/every, exe/rbe       the executables
 bridge/                  @rubyeverywhere/bridge — the JS half
-support/shell/           the Tauri desktop shell template
+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
+support/agents/          the AGENTS.md guide `every install --agents` writes
 ```
 
 The shell templates have their own READMEs documenting the freeze rules — what

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

data/bridge/everywhere/bridge.js

@@ -178,6 +178,19 @@ function detectPlatform() {
 
 // --- desktop: the Tauri-based RubyEverywhere shell -------------------------
 
+// Distinguishes concurrent desktop command calls. Only has to be unique within
+// one page, so a counter is enough; the random suffix just keeps two rapid
+// calls from colliding if the page is restored from bfcache mid-flight.
+let commandSequence = 0
+const COMMAND_TIMEOUT = 30000
+
+// The shell's own window handle. Named so it can't shadow the global `window`
+// inside the adapter below, where every other method still needs the real one.
+function tauriWindow() {
+  const api = window.__TAURI__ && window.__TAURI__.window
+  return api && api.getCurrentWindow ? api.getCurrentWindow() : null
+}
+
 const desktop = {
   notify({ title, body }) {
     return window.__TAURI__.event.emit("everywhere:notify", { title, body })
@@ -210,6 +223,56 @@ const desktop = {
     return window.__TAURI__.clipboardManager.readText()
   },
 
+  // Window controls, for apps that draw their own title bar (`window.title_bar:
+  // frameless`, and `overlay` on Windows/Linux where there's no native overlay
+  // style). Without a system title bar there's nothing to drag or click, so the
+  // page supplies both and calls these. One entry point rather than six methods
+  // because the Tauri window API is already uniform: every one of these is a
+  // no-arg call returning a promise.
+  //
+  // These are ACL-gated. The matching core:window:allow-* permissions have to be
+  // in BOTH capability sets (capabilities/default.json for local origins, and
+  // the mirrored list in authorize_remote_origin for remote mode) or they reject
+  // at runtime.
+  windowControl(action) {
+    const win = tauriWindow()
+    return win ? win[action]() : Promise.resolve(null)
+  },
+
+  // Call a Rust function the app keeps in native/desktop/. Events, not invoke:
+  // a RubyEverywhere page is always served over http (127.0.0.1 in local mode,
+  // your domain in remote mode) and Tauri v2 refuses invoke from any http
+  // origin — even the packaged app's own localhost server. See the comment on
+  // install_command_bridge in the shell's extension_host.rs.
+  //
+  // The id round-trips so concurrent calls can't take each other's answers,
+  // which a bare request/response event pair would otherwise allow.
+  desktopInvoke(name, payload) {
+    return new Promise((resolve, reject) => {
+      const id = `${commandSequence++}-${Math.random().toString(36).slice(2)}`
+      let off = null
+      const settle = (fn, value) => {
+        clearTimeout(timer)
+        if (off) off()
+        fn(value)
+      }
+      const timer = setTimeout(
+        () => settle(reject, new Error(`desktop command ${name} timed out`)),
+        COMMAND_TIMEOUT
+      )
+      off = this.on("command-result", (result) => {
+        if (!result || result.id !== id) return
+        if (result.ok) settle(resolve, result.value)
+        else settle(reject, new Error(result.error || `desktop command ${name} failed`))
+      })
+      window.__TAURI__.event.emit("everywhere:command", {
+        id,
+        name,
+        payload: payload === undefined ? null : payload
+      })
+    })
+  },
+
   // Ask the shell to check its update feed; resolve off whichever update
   // event answers first. The shell always replies to an explicit check
   // (available / none / error), the timeout is just a safety net.
@@ -295,6 +358,22 @@ const browser = {
     return null
   },
 
+  // A browser tab has no window of its own to drive — the one thing close()
+  // could map to (window.close) only works for script-opened windows, which
+  // this never is. Resolving null keeps a page that draws a custom title bar
+  // from throwing when it's opened in a plain browser.
+  windowControl() {
+    return Promise.resolve(null)
+  },
+
+  // There is no Rust here. Rejecting (rather than resolving null) is the honest
+  // answer: unlike the rest of the bridge, a desktop command has no web
+  // equivalent to degrade to, and silently resolving would let a page act on a
+  // result it never got. Gate on Everywhere.desktop.supported.
+  desktopInvoke(name) {
+    return Promise.reject(new Error(`desktop command ${name} is unavailable outside the desktop shell`))
+  },
+
   // Honest approximation: the Vibration API where it exists (Android
   // browsers); silently nothing elsewhere (iOS Safari has no equivalent).
   haptic(kind, value) {
@@ -764,6 +843,17 @@ const adapter = adapters[platform]
 // registered by the time app code first calls notify().
 if (platform === "mobile") installWebBridge()
 
+// Publish the window chrome mode to CSS. The titlebar utilities in native.css
+// key off this attribute, which is the only way they can know a mode that lives
+// in everywhere.yml — and it keeps them inert everywhere else, since nothing
+// stamps it in a browser tab, on mobile, or in a normally decorated window.
+if (platform === "desktop" && typeof document !== "undefined") {
+  const titleBar = config.window && config.window.title_bar
+  if (titleBar && titleBar !== "decorated") {
+    document.documentElement.dataset.everywhereTitlebar = titleBar
+  }
+}
+
 // Mutable so setChannel can keep updates.channel truthful without a reload.
 let updatesChannel = (config.updates && config.updates.channel) || null
 
@@ -1034,6 +1124,67 @@ export const Everywhere = {
     }
   },
 
+  // Rust the app keeps in native/desktop/ and declares under
+  // `native.desktop.commands` in everywhere.yml:
+  //
+  //   const ports = await Everywhere.desktop.invoke("scan_ports", { baud: 9600 })
+  //
+  // The payload arrives as serde_json::Value and whatever the command returns
+  // comes back as the resolved value. Errors reject with the command's own
+  // message. Rejects immediately off the desktop — there's no web fallback for
+  // "talk to a serial port", so check `supported` first.
+  desktop: {
+    get supported() {
+      return platform === "desktop"
+    },
+    invoke(name, payload) {
+      return adapter.desktopInvoke(name, payload)
+    }
+  },
+
+  // Desktop window controls, for apps that draw their own title bar. Set
+  // `window.title_bar: overlay` (macOS traffic lights float over your content)
+  // or `frameless` (no system chrome at all) in everywhere.yml; frameless is
+  // the one that needs these, since the page then owns dragging and the
+  // minimize/maximize/close buttons:
+  //
+  //   <header data-tauri-drag-region>
+  //     <button onclick="Everywhere.window.close()">×</button>
+  //   </header>
+  //
+  // Everything resolves to null in a browser tab and on mobile, where the OS
+  // owns the frame — so the same markup is safe everywhere.
+  window: {
+    get supported() {
+      return platform === "desktop"
+    },
+    minimize() {
+      return adapter.windowControl("minimize")
+    },
+    maximize() {
+      return adapter.windowControl("maximize")
+    },
+    unmaximize() {
+      return adapter.windowControl("unmaximize")
+    },
+    // What a double-click on a title bar normally does.
+    toggleMaximize() {
+      return adapter.windowControl("toggleMaximize")
+    },
+    close() {
+      return adapter.windowControl("close")
+    },
+    isMaximized() {
+      return adapter.windowControl("isMaximized").then((maximized) => !!maximized)
+    },
+    // Call from a pointerdown handler on your custom title bar. Tauri's
+    // data-tauri-drag-region attribute does this for you; this is the escape
+    // hatch for a drag region you compute yourself.
+    startDragging() {
+      return adapter.windowControl("startDragging")
+    }
+  },
+
   updates: {
     // True only when the shell actually has a feed to check (everywhere.yml
     // updates: url + public_key made it into the shipped config).

data/bridge/everywhere/native.css

@@ -201,3 +201,64 @@ html[data-bridge-platform] [data-everywhere-nav-menu] {
 @keyframes everywhere-sheet-rise {
   from { transform: translateY(1rem); opacity: 0; }
 }
+
+/* ---------------------------------------------------------------------------
+ * Desktop window chrome — for `window.title_bar: overlay | frameless` in
+ * everywhere.yml. The bridge stamps data-everywhere-titlebar on <html>, so
+ * every rule here is scoped to the mode that needs it: on mobile, in a plain
+ * browser tab, and in a normal decorated window the attribute is absent and
+ * these classes do nothing. Safe to apply unconditionally.
+ * ------------------------------------------------------------------------- */
+
+:root {
+  /* macOS traffic lights: a ~78px cluster inside a 28px band at the top left.
+   * Override both if you draw a taller bar. */
+  --everywhere-titlebar-height: 28px;
+  --everywhere-titlebar-controls: 78px;
+}
+
+/* Overlay mode: the system still draws (and positions) the traffic lights over
+ * your page. Reserve the band so your content doesn't slide underneath them.
+ * Frameless draws no controls at all, so it reserves nothing — the page owns
+ * that space and decides what goes there. */
+[data-everywhere-titlebar="overlay"] .everywhere-titlebar-inset {
+  padding-top: var(--everywhere-titlebar-height);
+}
+[data-everywhere-titlebar="overlay"] .everywhere-titlebar-controls-inset {
+  padding-left: var(--everywhere-titlebar-controls);
+}
+
+/* A title-bar strip across the top of the window. Purely layout — the shell
+ * already makes the top 28px drag the window, so this needs no attribute:
+ *
+ *   <header class="everywhere-titlebar">My App</header>
+ *
+ * Buttons and links inside it keep their clicks. Mark a region outside the
+ * strip with data-tauri-drag-region to make that draggable too, or set
+ * window.drag_height: 0 in everywhere.yml to take dragging over entirely.
+ *
+ * In overlay mode it clears the traffic lights; in frameless it starts at the
+ * left edge, because there's nothing there to clear. */
+[data-everywhere-titlebar] .everywhere-titlebar {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  height: var(--everywhere-titlebar-height);
+  user-select: none;
+  -webkit-user-select: none;
+  cursor: default;
+}
+[data-everywhere-titlebar="overlay"] .everywhere-titlebar {
+  padding-left: var(--everywhere-titlebar-controls);
+}
+
+/* Anything clickable inside the drag strip has to opt out, or the drag region
+ * swallows the click before the control ever sees it. */
+[data-everywhere-titlebar] .everywhere-titlebar button,
+[data-everywhere-titlebar] .everywhere-titlebar a,
+[data-everywhere-titlebar] .everywhere-titlebar input,
+[data-everywhere-titlebar] .everywhere-titlebar select,
+[data-everywhere-titlebar] .everywhere-titlebar [data-tauri-drag-region="false"] {
+  -webkit-app-region: no-drag;
+  cursor: default;
+}

data/lib/everywhere/agents_guide.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "paths"
+require_relative "ui"
+
+module Everywhere
+  # The AGENTS.md guide `every install --agents` writes into an app, so AI coding
+  # agents (Claude Code, Cursor, Copilot, Codex) understand what RubyEverywhere is
+  # before they "fix" the config edits install made.
+  #
+  # The guide is prose, so it lives as markdown under support/agents/ rather than
+  # in a heredoc — code fences and #{} snippets are miserable to escape in Ruby,
+  # and the gemspec already globs support/**/*. Assembly is a shared body plus
+  # per-framework fragments (install notes, view helpers) and a mode fragment,
+  # joined by {{PLACEHOLDER}} gsub.
+  module AgentsGuide
+    module_function
+
+    # The generated section is fenced so a re-run can refresh it without touching
+    # anything the app's own authors wrote around it.
+    BEGIN_MARKER = "<!-- rubyeverywhere:begin -->"
+    END_MARKER   = "<!-- rubyeverywhere:end -->"
+
+    PLACEHOLDER = /\{\{([A-Z_]+)\}\}/
+    LABELS = { "rails" => "Rails", "sinatra" => "Sinatra", "hanami" => "Hanami" }.freeze
+
+    def template_dir = File.join(Paths.gem_root, "support", "agents")
+
+    # The guide body for one app, with no markers around it.
+    def render(framework:, mode:)
+      substitute(read("AGENTS.md"),
+        "FRAMEWORK" => LABELS.fetch(framework),
+        "MODE" => mode,
+        "FRAMEWORK_NOTES" => read("frameworks", "#{framework}.md").strip,
+        "FRAMEWORK_VIEWS" => read("frameworks", "#{framework}-views.md").strip,
+        "MODE_NOTES" => read("modes", "#{mode}.md").strip)
+    end
+
+    # The body wrapped in the markers, ready to splice into an AGENTS.md.
+    def block(framework:, mode:)
+      "#{BEGIN_MARKER}\n#{render(framework: framework, mode: mode).strip}\n#{END_MARKER}\n"
+    end
+
+    # fetch, not [], so a typo'd placeholder blows up in the test suite instead of
+    # shipping "{{MDOE}}" to somebody's repo.
+    def substitute(body, values)
+      body.gsub(PLACEHOLDER) { values.fetch(Regexp.last_match(1)) }
+    end
+
+    def read(*parts)
+      path = File.join(template_dir, *parts)
+      File.exist?(path) or UI.die!("couldn't find the bundled AGENTS.md template at #{path}; " \
+                                   "reinstall ruby_everywhere")
+      File.read(path)
+    end
+  end
+end

data/lib/everywhere/auth_handoff.rb

@@ -151,8 +151,14 @@ module Everywhere
     # A provider path requested from inside the shell's web view — the visits
     # the shell couldn't intercept natively (a `data-turbo="false"` link, or the
     # POST that OmniAuth 2 requires). Bounce to a page that can ask it to.
+    #
+    # mobile_platform_of, not native_platform_of: the whole handoff exists
+    # because a phone shell must open the provider in ASWebAuthenticationSession
+    # / Custom Tabs. The desktop shell already sends external links to the system
+    # browser, so diverting there would bounce sign-in to a page nothing can
+    # complete.
     def divert(env, config)
-      return nil unless Everywhere.native_platform_of(env["HTTP_USER_AGENT"])
+      return nil unless Everywhere.mobile_platform_of(env["HTTP_USER_AGENT"])
       return nil unless config.oauth_path?(env["PATH_INFO"])
 
       redirect("#{NATIVE}?#{Rack::Utils.build_query("to" => path_with_query(env))}")
@@ -172,7 +178,7 @@ module Everywhere
       # Only ever the auth browser: inside the web view the app is already
       # holding the jar we would be handing it, and a stale marker there must
       # not divert an ordinary visit into a callback URL it can't open.
-      marker = auth_marker(env) unless Everywhere.native_platform_of(env["HTTP_USER_AGENT"])
+      marker = auth_marker(env) unless Everywhere.mobile_platform_of(env["HTTP_USER_AGENT"])
       return @app.call(env) if marker.nil? || config.oauth_path?(env["PATH_INFO"]) || !navigation?(env)
 
       _, headers, body = @app.call(env)