Add Platform.System.os_description/0 for backend-safe OS info

Replace direct :wx_misc.getOsDescription/0 usage so apps can read a
device/OS description on Wx, Json/mobile bridge, and Browser backends
without depending on the Hex Bridge GenServer.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: dominicletz

CHANGELOG.md

@@ -8,6 +8,7 @@
 - Optional `config :desktop, :backend, :auto | :wx | :json | :browser` override
 - Menu adapters: `Desktop.Menu.Adapter.Json` and `Desktop.Menu.Adapter.Browser`
 - Public `Desktop.*` APIs unchanged (`Desktop.Window`, `Desktop.Env`, `Desktop.Menu`, etc.)
+- `Desktop.Platform.System.os_description/0` — backend-safe replacement for `:wx_misc.getOsDescription/0` (Wx, Json bridge, Browser)
 - Test suite: `mix test.fast`, `xvfb-run mix test.wx`, `mix test.guard` — see `docs/TEST_PLAN.md`
 - Compile without OTP `:wx`: conditional `erl_src_paths` and `Desktop.Wx` fallbacks (no `wx.hrl` required)
 

guides/faq.md

@@ -48,6 +48,8 @@ Inspect what the active backend supports:
 ```elixir
 Desktop.Platform.backend()       # e.g. Desktop.Backend.Wx
 Desktop.Platform.capabilities()  # %{window: true, content: :webview, ...}
+Desktop.Platform.System.locale()
+Desktop.Platform.System.os_description()  # replaces :wx_misc.getOsDescription/0
 ```
 
 | Backend | `window` | `content` | `menu` |

lib/desktop/backend/browser.ex

@@ -45,6 +45,9 @@ defmodule Desktop.Backend.Browser do
   @impl true
   def open_external_url(url), do: Desktop.Impl.HostBrowser.open(url)
 
+  @impl true
+  def os_description, do: nil
+
   @impl true
   def activate_event_active?(_event), do: true
 

lib/desktop/backend/json.ex

@@ -77,6 +77,11 @@ defmodule Desktop.Backend.Json do
     :ok
   end
 
+  @impl true
+  def os_description do
+    Protocol.call(:wx_misc, :getOsDescription, [])
+  end
+
   @impl true
   def activate_event_active?(_event), do: true
 

lib/desktop/backend/wx.ex

@@ -75,6 +75,11 @@ defmodule Desktop.Backend.Wx do
     end
   end
 
+  @impl true
+  def os_description do
+    Null.wx_call(:wx_misc, :getOsDescription, [])
+  end
+
   @impl true
   def activate_event_active?(event) do
     if function_exported?(:wxActivateEvent, :getActive, 1) do

lib/desktop/bridge/mock.ex

@@ -14,6 +14,7 @@ defmodule Desktop.Bridge.Mock do
   def handle_method([:wx, :getObjectType, [arg]]), do: Keyword.get(arg, :type)
   def handle_method([:wxLocale | _]), do: ~c"en"
   def handle_method([:wx_misc, :launchDefaultBrowser | _]), do: :ok
+  def handle_method([:wx_misc, :getOsDescription | _]), do: ~c"Mock OS"
 
   def handle_method([type, :new | args]),
     do: [id: System.unique_integer([:positive]), type: type, args: args]

lib/desktop/platform/system.ex

@@ -17,6 +17,7 @@ defmodule Desktop.Platform.System do
               term()
   @callback wx_available?() :: boolean()
   @callback open_external_url(String.t()) :: :ok
+  @callback os_description() :: String.t() | charlist() | nil
   @callback activate_event_active?(event :: term()) :: boolean()
 
   def init_env, do: impl().init_env()
@@ -32,6 +33,33 @@ defmodule Desktop.Platform.System do
   def wx_available?, do: impl().wx_available?()
   def open_external_url(url), do: Helpers.with_wx_env(fn -> impl().open_external_url(url) end)
 
+  @doc """
+  Returns a human-readable OS / device description string.
+
+  Replaces direct `:wx_misc.getOsDescription/0` calls so apps work on all
+  backends (Wx, Json/mobile bridge, Browser). Returns `nil` when unavailable.
+  """
+  def os_description do
+    Helpers.with_wx_env(fn ->
+      case impl().os_description() do
+        nil -> nil
+        desc when is_list(desc) -> List.to_string(desc)
+        desc when is_binary(desc) -> desc
+        _ -> nil
+      end
+    end)
+    |> case do
+      nil ->
+        nil
+
+      str ->
+        case String.trim(str) do
+          "" -> nil
+          other -> other
+        end
+    end
+  end
+
   def activate_event_active?(event),
     do: Helpers.with_wx_env(fn -> impl().activate_event_active?(event) end)
 

test/desktop/backend/browser_test.exs

@@ -37,6 +37,7 @@ defmodule Desktop.Backend.BrowserTest do
     assert :ok = Browser.set_env(nil)
     assert Browser.get_env() == nil
     assert Browser.locale() == nil
+    assert Browser.os_description() == nil
     refute Browser.wx_available?()
   end
 end

test/desktop/backend/json_test.exs

@@ -27,6 +27,11 @@ defmodule Desktop.Backend.JsonTest do
     assert Json.locale() == "en"
   end
 
+  test "T-JSN: os_description via bridge RPC" do
+    assert Json.os_description() == ~c"Mock OS"
+    assert Desktop.Platform.System.os_description() == "Mock OS"
+  end
+
   test "T-JSN: new frame handle shape" do
     wx = Transport.ensure_started()
 

test/desktop/backend/wx_test.exs

@@ -39,4 +39,9 @@ defmodule Desktop.Backend.WxTest do
     result = Wx.locale()
     assert result == nil or is_binary(result)
   end
+
+  test "T-WX: os_description via Platform.System" do
+    result = Desktop.Platform.System.os_description()
+    assert result == nil or is_binary(result)
+  end
 end