iterm2_ruby 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ea8b3aab793d0294a0cb9f726e8cc01123b0da6a22b02034a7f64c3e4744959
-  data.tar.gz: 3773d06e8c6969221bb52049ff3a11131a786f8280d36e3f5a889174c3a56d17
+  metadata.gz: '005262752689643c56c4a97896c3b923f422c4ff49dd5c310664dcefbe7f4c2a'
+  data.tar.gz: 332e89ff558b000f3f69d35102587a051b48db11818bafeba03c34621feab9f3
 SHA512:
-  metadata.gz: ecff09efcb6229d0079eff7f8cc324fb0da17287c762f39fb1e99ada8c2476283373ed6ef48c097c3c36f6fe87346485c3b311133f0ca45be22e5f60940da729
-  data.tar.gz: 143e8af32d29624720bb35719eb399e620364c0e632bc5613ea710190acd0c8a5b8c3112a150db5794ff8da1968a6c39d38d1288626366ee9231ddf9810c63f5
+  metadata.gz: 2f9294eb24b0e60b62954296a1ee675a9107b9caea7e6cf75fb1c36429740c0219cae2c0dfa1710d303007f024b713ab5fb5b7f0a8ada62915b6a5fcac4668a8
+  data.tar.gz: fdb38625258e956ae0fef7be027a099739fda95c256a7b6bd2be5e7034bc13e16c885fbed94b26a230a5efded8334a6e4e907be58ed978d0bf0c2f7bfd4a804b

data/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.4.0] - 2026-10-23
+
+### Added
+- `client.split_browser_pane(session_id, url, vertical: true)` -- split a pane that shows a URL as a web view.
+  Uses the `"Custom Command" => "Browser"` profile override, so no "Web Browser" profile is needed.
+- `ITerm2::Browser` -- connection-free probes (`plugin_installed?`, `profiles_enabled?`, `available?`) and
+  `pane_properties(url)`. The plugin check looks in the usual install folders first and asks Spotlight only
+  as a fallback, so a plugin in those folders never depends on a Spotlight lookup. Probe commands run without a
+  shell and are terminated on timeout.
+- `ITerm2.current_session_id` -- the calling pane's session ID from `ITERM_SESSION_ID`, `nil` outside iTerm2.
+
 ## [0.3.1] - 2026-09-04
 
 ### Fixed

data/README.md

@@ -35,12 +35,14 @@ This feeds a real-time "mission control" view over a whole fleet of sessions.
 **Split a pane and pop a live browser preview next to your code:**
 
 ```ruby
-ITerm2.connect do |c|
-  c.split_pane(guid, vertical: true, profile_name: "Web Browser",
-               profile_customizations: { "Initial URL" => url })
+here = ITerm2.current_session_id            # nil outside iTerm2
+if here && ITerm2::Browser.available?       # Browser Plugin installed, browser-style profiles on
+  ITerm2.connect { |c| c.split_browser_pane(here, url, vertical: true) }
 end
 ```
 
+No "Web Browser" profile needs to exist; the pane's profile is overridden to show the URL.
+
 **Spawn a background task in its own window, no permission dialogs:**
 
 ```bash
@@ -214,6 +216,7 @@ Most commands accept `--session ID`, `--tab ID`, or `--window ID` to target a sp
 | `raise_by_cwd(pattern)` | Raise first session matching cwd |
 | `create_tab(window_id:, profile_name:)` | Create a new tab |
 | `split_pane(session_id, vertical:)` | Split a pane |
+| `split_browser_pane(session_id, url, vertical:)` | Split a pane that shows a URL as a web view (check `ITerm2::Browser.available?`) |
 | `close_session(session_id)` | Close a session |
 | `close_tab(tab_id)` | Close a tab |
 | `reorder_tabs(window_id => [tab_ids])` | Move/reorder tabs across windows |

data/docs/api.md

@@ -28,6 +28,12 @@ Creates a persistent client with an open connection. Equivalent to `ITerm2.conne
 
 Closes the connection. Unsubscribes all notification listeners and stops the dispatch thread if running.
 
+### `ITerm2.current_session_id(env = ENV)` -> String | nil
+
+The session ID of the pane the calling process runs in: the GUID after the colon of `ITERM_SESSION_ID`
+(`"w0t0p0:<GUID>"`). `nil` outside iTerm2 or when the value is not that shape. This is the ID every
+session-targeted call takes.
+
 ---
 
 ## Topology
@@ -188,6 +194,33 @@ Splits a pane. Returns the new session ID.
 
 **Raises:** `RPCError` on failure.
 
+### `client.split_browser_pane(session_id, url, vertical: true)` -> String
+
+Splits a pane that shows `url` as a web view (a browser pane), beside `session_id`. Returns the new session ID.
+It is `split_pane` with the profile overrides `"Custom Command" => "Browser"` and `"Initial URL" => url`, so no
+"Web Browser" profile has to be installed. iTerm2 still needs its separately installed Browser Plugin and the
+"Enable browser-style profiles" Advanced setting (on by default); check with `ITerm2::Browser.available?`.
+
+- **session_id** (String) -- session to split
+- **url** (String) -- page the pane loads
+- **vertical** (Boolean) -- `true` for a vertical split, `false` for horizontal
+
+**Raises:** `RPCError` on failure.
+
+Pass a real session ID: with `nil`, `split_pane` sends no session and iTerm2 chooses which pane to split.
+When calling with `ITerm2.current_session_id`, guard against `nil` (outside iTerm2).
+
+### `ITerm2::Browser`
+
+Connection-free checks for browser panes. Off macOS, `plugin_installed?`, `profiles_enabled?` and `available?` return `false`.
+When a check cannot tell (a failed or timed-out probe), the two differ on purpose: `plugin_installed?` returns `false`
+(a pane that cannot work should not be attempted) and `profiles_enabled?` returns `true` (the setting ships enabled).
+
+- `ITerm2::Browser.plugin_installed?` -- the Browser Plugin is in `/Applications` or `~/Applications`, or Spotlight finds it by bundle identifier
+- `ITerm2::Browser.profiles_enabled?` -- the "Enable browser-style profiles" setting is not turned off (unset counts as enabled)
+- `ITerm2::Browser.available?` -- both of the above
+- `ITerm2::Browser.pane_properties(url)` -- the profile overrides `split_browser_pane` applies; returns a Hash on every platform
+
 ### `client.close_session(session_id, force: false)` -> true | false
 
 Closes a session. With `force: true`, skips the confirmation prompt.

data/lib/iterm2/browser.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "timeout"
+
+module ITerm2
+  # iTerm2 draws a pane as a web view instead of a shell when its profile's
+  # "Custom Command" is the literal string "Browser" -- exactly how iTerm2's own
+  # built-in "Web Browser" profile is defined. Overriding that property (plus
+  # "Initial URL") on a split produces a browser pane from ANY base profile, so
+  # no "Web Browser" profile needs to be installed.
+  #
+  # iTerm2's own browser feature still needs two things this override cannot
+  # bypass: the separately downloaded Browser Plugin, and the "Enable
+  # browser-style profiles" Advanced setting (on by default). The probes below
+  # check both without opening an API connection.
+  module Browser
+    PROFILE_PROPERTIES = { "Custom Command" => "Browser" }.freeze
+
+    # The plugin's own CFBundleIdentifier (iterm2.com/browser-plugin.html).
+    PLUGIN_BUNDLE_ID = "com.googlecode.iterm2.iTermBrowserPlugin"
+
+    # Persisted key of Settings > Advanced > "Enable browser-style profiles".
+    # Unset on a machine that never touched it; iTerm2 treats that as enabled.
+    PROFILES_PREF_KEY = "browserProfiles"
+
+    # Where the plugin is normally unzipped. Checked first: a directory test is
+    # instant and deterministic, where a cold Spotlight (mdfind) lookup can take
+    # seconds and would read as "not installed" if it hit the timeout.
+    PLUGIN_PATHS = [
+      "/Applications/iTermBrowserPlugin.app",
+      File.join(Dir.home, "Applications", "iTermBrowserPlugin.app")
+    ].freeze
+
+    PROBE_TIMEOUT = 5
+    SPOTLIGHT_TIMEOUT = 15
+
+    # The profile properties that turn a split into a browser pane showing `url`.
+    def self.pane_properties(url)
+      PROFILE_PROPERTIES.merge("Initial URL" => url)
+    end
+
+    # True when the Browser Plugin is installed: in a usual location, or found
+    # by bundle identifier wherever it was unzipped. False on any doubt: not
+    # macOS, mdfind missing or erroring, timeout.
+    def self.plugin_installed?
+      return false unless darwin?
+      return true if PLUGIN_PATHS.any? { |path| File.directory?(path) }
+
+      found = capture("mdfind", "kMDItemCFBundleIdentifier == '#{PLUGIN_BUNDLE_ID}'", timeout: SPOTLIGHT_TIMEOUT)
+      !found.strip.empty?
+    rescue StandardError
+      false
+    end
+
+    # True unless the user explicitly turned off browser-style profiles. An
+    # unset preference reads as enabled. Not macOS: false. Any probe failure:
+    # true (the setting ships enabled, so doubt should not block).
+    def self.profiles_enabled?
+      return false unless darwin?
+
+      capture("defaults", "read", "com.googlecode.iterm2", PROFILES_PREF_KEY, timeout: PROBE_TIMEOUT).strip != "0"
+    rescue StandardError
+      true
+    end
+
+    # Whether a browser pane can be expected to work on this machine.
+    def self.available?
+      plugin_installed? && profiles_enabled?
+    end
+
+    def self.darwin?
+      RbConfig::CONFIG["host_os"].match?(/darwin/)
+    end
+
+    # Runs `command` without a shell and returns its stdout. On timeout the
+    # child is terminated, not left running, and Timeout::Error is raised.
+    def self.capture(*command, timeout:)
+      IO.popen(command, err: File::NULL) do |io|
+        Timeout.timeout(timeout) { io.read }
+      rescue Timeout::Error
+        terminate(io.pid)
+        raise
+      end
+    end
+
+    def self.terminate(pid)
+      Process.kill("TERM", pid)
+    rescue Errno::ESRCH
+      nil # already gone
+    end
+
+    private_class_method :darwin?, :capture, :terminate
+  end
+end

data/lib/iterm2/client.rb

@@ -159,6 +159,14 @@ module ITerm2
       resp.session_id.first
     end
 
+    # --- Browser panes ---
+
+    # Splits `session_id` with a pane that shows `url` as a web view. Returns the
+    # new session ID. See ITerm2::Browser for what iTerm2 needs for this to work.
+    def split_browser_pane(session_id, url, vertical: true)
+      split_pane(session_id, vertical: vertical, profile_customizations: Browser.pane_properties(url))
+    end
+
     # --- ReorderTabs ---
 
     def reorder_tabs(assignments)

data/lib/iterm2/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ITerm2
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/iterm2.rb

@@ -3,6 +3,7 @@
 require_relative "iterm2/version"
 require_relative "iterm2/proto/api_pb"
 require_relative "iterm2/connection"
+require_relative "iterm2/browser"
 require_relative "iterm2/client"
 require_relative "iterm2/window"
 require_relative "iterm2/tab"
@@ -19,6 +20,18 @@ module ITerm2
   class NotFoundError < RPCError; end
   class SubscriptionError < Error; end
 
+  # The session ID of the pane the calling process runs in, or nil outside
+  # iTerm2. ITERM_SESSION_ID looks like "w0t0p0:<GUID>"; the GUID after the
+  # colon is the ID every API call takes. A value with no colon is not that
+  # shape, so it returns nil rather than a meaningless string.
+  def self.current_session_id(env = ENV)
+    raw = env["ITERM_SESSION_ID"]
+    return nil unless raw&.include?(":")
+
+    id = raw.split(":", 2).last
+    id.empty? ? nil : id
+  end
+
   # Convenience: open connection, yield client, close
   def self.connect(app_name: "iterm2_ruby")
     client = Client.new(app_name: app_name)

data/llms.txt

@@ -64,11 +64,22 @@ States: `:editing`, `:running`, `:at_prompt`, `:unavailable`.
 ## Other Methods
 
 `topology_enriched`, `list_sessions`, `activate_tab`, `activate_window`,
-`raise_by_cwd`, `create_tab`, `split_pane`, `close_session`, `close_tab`,
+`raise_by_cwd`, `create_tab`, `split_pane`, `split_browser_pane`, `close_session`, `close_tab`,
 `set_profile_property`, `get_profile_property`, `list_profiles`, `get_property`,
 `set_property`, `window_frame`, `set_window_frame`, `set_session_grid_size`,
 `get_variables`, `set_variables`, `inject`, `reorder_tabs`, `topology_for_aggregator`.
 
+## Browser panes (split a web view beside a session)
+
+```ruby
+here = ITerm2.current_session_id    # the calling pane's id from ENV["ITERM_SESSION_ID"]; nil outside iTerm2
+if here && ITerm2::Browser.available?   # plugin installed AND browser-style profiles enabled (macOS only; no API connection)
+  ITerm2.connect { |c| c.split_browser_pane(here, "http://localhost:4579/ambient", vertical: true) }  # => new session id
+end
+```
+
+No "Web Browser" profile is needed: the method overrides the new pane's profile ("Custom Command" => "Browser", "Initial URL" => url). iTerm2's separately installed Browser Plugin must be present; `ITerm2::Browser.available?` checks that. Always pass a real session id (with nil, iTerm2 picks which pane to split). Callers keep their own platform guard and fallback (e.g. system browser off iTerm2). Never use the Python `iterm2` package.
+
 ## Notifications
 
 ```ruby

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iterm2_ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Forrest Chang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -43,6 +43,7 @@ files:
 - docs/cli.md
 - iterm2_ruby.gemspec
 - lib/iterm2.rb
+- lib/iterm2/browser.rb
 - lib/iterm2/client.rb
 - lib/iterm2/connection.rb
 - lib/iterm2/proto/api_pb.rb