zui 0.0.1 → 0.0.3

data/lib/zui/client.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "net/http"
+require "openssl"
+require "tmpdir"
+require "timeout"
+require "uri"
+require "zlib"
+require "rubygems/package"
+
+module Zui
+  class Client
+    FORMAT = 1
+    MAX_ARCHIVE_BYTES = 1_073_741_824
+    MAX_EXPANDED_BYTES = 2_147_483_648
+    MAX_ENTRIES = 100_000
+    REDIRECT_LIMIT = 5
+
+    attr_reader :platform, :version
+
+    def initialize(platform: Platform.current, version: VERSION, environment: ENV,
+                   cache_root: nil, release_base_url: nil, downloader: nil)
+      @platform = platform.assert_supported!
+      @version = version.to_s
+      @environment = environment
+      @cache_root = cache_root
+      @release_base_url = release_base_url
+      @downloader = downloader || method(:download)
+    end
+
+    def root
+      override = @environment["ZUI_CLIENT_ROOT"]
+      return File.expand_path(override) if override && !override.empty?
+
+      File.join(cache_root, "zui", "clients", version, platform.id)
+    end
+
+    def configured?
+      validate!(root)
+      true
+    rescue ArgumentError, Errno::ENOENT
+      false
+    end
+
+    def configure!
+      return root if configured?
+      raise ArgumentError, "ZUI_CLIENT_ROOT is not a valid configured client: #{root}" if client_root_override?
+
+      FileUtils.mkdir_p(File.dirname(root))
+      File.open("#{root}.lock", File::RDWR | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        return root if configured?
+
+        install_download!
+      end
+      root
+    end
+
+    def executable
+      manifest = validate!(root)
+      File.join(root, manifest.fetch("executable"))
+    end
+
+    def executable_relative_path
+      validate!(root).fetch("executable")
+    end
+
+    def environment_entries
+      manifest = validate!(root)
+      manifest.fetch("environment", {}).transform_values do |paths|
+        Array(paths).map { |path| safe_manifest_path!(path, "client environment path") }
+      end
+    end
+
+    def environment(base = ENV.to_h, client_root: root)
+      environment_entries.each_with_object(base.to_h.dup) do |(name, paths), result|
+        unless name.match?(/\A[A-Z][A-Z0-9_]*\z/)
+          raise ArgumentError, "invalid environment variable in Zui client: #{name.inspect}"
+        end
+
+        resolved = paths.map { |path| File.join(client_root, path) }
+        previous = result[name]
+        resolved << previous unless previous.nil? || previous.empty?
+        result[name] = resolved.join(File::PATH_SEPARATOR)
+      end
+    end
+
+    def copy_to(destination)
+      manifest = validate!(root)
+      raise ArgumentError, "client destination already exists: #{destination}" if File.exist?(destination)
+
+      created = true
+      FileUtils.mkdir_p(destination)
+      FileUtils.cp_r(Dir.children(root).map { |entry| File.join(root, entry) }, destination)
+      validate!(destination)
+      manifest
+    rescue StandardError
+      FileUtils.remove_entry(destination) if created && destination && File.exist?(destination)
+      raise
+    end
+
+    def manifest
+      validate!(root)
+    end
+
+    def archive_name = "zui-client-#{platform.id}.tar.gz"
+
+    def archive_url
+      override = @environment["ZUI_CLIENT_ARCHIVE"]
+      return File.expand_path(override) if override && !override.empty?
+
+      URI.join("#{release_base_url}/", archive_name)
+    end
+
+    def checksum_url
+      override = @environment["ZUI_CLIENT_CHECKSUM"]
+      return File.expand_path(override) if override && !override.empty?
+
+      source = archive_url
+      source.is_a?(URI) ? URI("#{source}.sha256") : "#{source}.sha256"
+    end
+
+    private
+
+    def install_download!
+      Dir.mktmpdir(".zui-client-", File.dirname(root)) do |temporary|
+        archive = File.join(temporary, archive_name)
+        checksum = "#{archive}.sha256"
+        @downloader.call(archive_url, archive)
+        @downloader.call(checksum_url, checksum)
+        verify_checksum!(archive, checksum)
+
+        staged = File.join(temporary, "client")
+        FileUtils.mkdir_p(staged)
+        extract!(archive, staged)
+        validate!(staged)
+
+        installed = "#{root}.install-#{Process.pid}-#{rand(1_000_000)}"
+        File.rename(staged, installed)
+        if File.exist?(root)
+          invalid = "#{root}.invalid-#{Time.now.to_i}-#{Process.pid}"
+          File.rename(root, invalid)
+        end
+        File.rename(installed, root)
+      ensure
+        FileUtils.remove_entry(installed) if installed && File.exist?(installed)
+      end
+      validate!(root)
+      root
+    end
+
+    def validate!(directory)
+      manifest_path = File.join(directory, "client.json")
+      raise ArgumentError, "Zui client manifest not found: #{manifest_path}" unless File.file?(manifest_path)
+      raise ArgumentError, "Zui client manifest is too large" if File.size(manifest_path) > 65_536
+
+      manifest = JSON.parse(File.read(manifest_path))
+      raise ArgumentError, "invalid Zui client manifest root" unless manifest.is_a?(Hash)
+      expected = {
+        "format" => FORMAT,
+        "framework" => "zui",
+        "client_version" => version,
+        "platform" => platform.id
+      }
+      expected.each do |key, value|
+        actual = manifest[key]
+        raise ArgumentError, "invalid Zui client #{key}: expected #{value.inspect}, got #{actual.inspect}" unless actual == value
+      end
+      raise ArgumentError, "Zui client is not bundle capable" unless manifest["bundle_capable"] == true
+      unless manifest["payload"] == %w[native-host qt-engine]
+        raise ArgumentError, "invalid Zui client payload: expected native host and Qt engine only"
+      end
+
+      required_paths = manifest["required_paths"]
+      unless required_paths.is_a?(Array) && !required_paths.empty? &&
+             required_paths.all? { |path| path.is_a?(String) }
+        raise ArgumentError, "invalid Zui client required paths"
+      end
+      required_paths.each do |path|
+        relative_path = safe_manifest_path!(path, "client required path")
+        resolved_path = File.join(directory, relative_path)
+        raise ArgumentError, "Zui client required path is missing: #{resolved_path}" unless File.exist?(resolved_path)
+      end
+
+      relative = safe_manifest_path!(manifest["executable"], "client executable")
+      executable = File.join(directory, relative)
+      unless File.file?(executable) && executable_for_target?(executable)
+        raise ArgumentError, "Zui client executable is missing or not executable: #{executable}"
+      end
+
+      client_environment = manifest.fetch("environment", {})
+      raise ArgumentError, "invalid Zui client environment" unless client_environment.is_a?(Hash)
+      client_environment.each do |name, paths|
+        unless name.is_a?(String) && name.match?(/\A[A-Z][A-Z0-9_]*\z/)
+          raise ArgumentError, "invalid client environment entry: #{name.inspect}"
+        end
+        unless paths.is_a?(Array) && !paths.empty? && paths.all? { |path| path.is_a?(String) }
+          raise ArgumentError, "invalid client environment paths for #{name}"
+        end
+        paths.each do |path|
+          relative_path = safe_manifest_path!(path, "client environment path")
+          resolved_path = File.join(directory, relative_path)
+          raise ArgumentError, "Zui client environment path is missing: #{resolved_path}" unless File.exist?(resolved_path)
+        end
+      end
+      manifest
+    rescue JSON::ParserError => error
+      raise ArgumentError, "invalid Zui client manifest: #{error.message}"
+    end
+
+    def executable_for_target?(path)
+      # Windows cannot represent the POSIX executable bit when validating a
+      # Linux or macOS archive. Native POSIX clients still require that bit.
+      platform.windows? || Gem.win_platform? || File.executable?(path)
+    end
+
+    def verify_checksum!(archive, checksum_file)
+      expected = File.read(checksum_file, 4096)[/\A\s*([0-9a-fA-F]{64})(?:\s|\z)/, 1]
+      raise ArgumentError, "invalid Zui client checksum file" unless expected
+
+      actual = Digest::SHA256.file(archive).hexdigest
+      raise ArgumentError, "Zui client checksum mismatch" unless actual.casecmp?(expected)
+    end
+
+    def extract!(archive, destination)
+      count = 0
+      expanded = 0
+      Zlib::GzipReader.open(archive) do |gzip|
+        Gem::Package::TarReader.new(gzip) do |tar|
+          tar.each do |entry|
+            count += 1
+            raise ArgumentError, "Zui client archive contains too many files" if count > MAX_ENTRIES
+
+            relative = safe_relative_path!(entry.full_name, "archive entry")
+            target = File.join(destination, relative)
+            if entry.directory?
+              FileUtils.mkdir_p(target)
+            elsif entry.file?
+              expanded += entry.header.size
+              raise ArgumentError, "Zui client archive expands beyond the safety limit" if expanded > MAX_EXPANDED_BYTES
+
+              FileUtils.mkdir_p(File.dirname(target))
+              File.open(target, "wb", entry.header.mode & 0o111 == 0 ? 0o644 : 0o755) do |file|
+                IO.copy_stream(entry, file)
+              end
+            else
+              raise ArgumentError, "Zui client archive contains an unsupported link or special file: #{entry.full_name}"
+            end
+          end
+        end
+      end
+    rescue Zlib::GzipFile::Error, Gem::Package::TarInvalidError => error
+      raise ArgumentError, "invalid Zui client archive: #{error.message}"
+    end
+
+    def download(source, destination, redirects = REDIRECT_LIMIT)
+      if source.is_a?(String) && File.file?(source)
+        FileUtils.cp(source, destination)
+        return destination
+      end
+      uri = source.is_a?(URI) ? source : URI(source.to_s)
+      if uri.scheme == "file"
+        FileUtils.cp(URI::DEFAULT_PARSER.unescape(uri.path), destination)
+        return destination
+      end
+      raise ArgumentError, "Zui client download must use HTTPS" unless uri.scheme == "https"
+      raise ArgumentError, "too many Zui client download redirects" if redirects.negative?
+
+      http = Net::HTTP.new(uri.host, uri.port, :ENV)
+      http.use_ssl = true
+      http.open_timeout = 20
+      http.read_timeout = 120
+      http.write_timeout = 120 if http.respond_to?(:write_timeout=)
+      http.start do
+        http.request(Net::HTTP::Get.new(uri.request_uri)) do |response|
+          case response
+          when Net::HTTPSuccess
+            written = 0
+            File.open(destination, "wb") do |file|
+              response.read_body do |chunk|
+                written += chunk.bytesize
+                raise ArgumentError, "Zui client download exceeds the safety limit" if written > MAX_ARCHIVE_BYTES
+                file.write(chunk)
+              end
+            end
+          when Net::HTTPRedirection
+            location = response["location"] || raise(ArgumentError, "Zui client redirect has no location")
+            return download(URI.join(uri, location), destination, redirects - 1)
+          else
+            raise ArgumentError, "Zui client download failed: HTTP #{response.code}"
+          end
+        end
+      end
+      destination
+    rescue URI::InvalidURIError => error
+      raise ArgumentError, "invalid Zui client URL: #{error.message}"
+    rescue Timeout::Error, SocketError, OpenSSL::SSL::SSLError => error
+      raise ArgumentError, "Zui client download failed: #{error.class}: #{error.message}"
+    end
+
+    def safe_relative_path!(value, label)
+      path = value.to_s
+      if path.empty? || path.include?("\\") || path.match?(/[[:cntrl:]]/) || path.start_with?("/") ||
+         path.match?(/\A[A-Za-z]:/) ||
+         path.split("/").any? { |part| part.empty? || part == "." || part == ".." }
+        raise ArgumentError, "unsafe #{label}: #{value.inspect}"
+      end
+      path
+    end
+
+    def safe_manifest_path!(value, label)
+      path = safe_relative_path!(value, label)
+      unless path.match?(/\A[A-Za-z0-9._+ -]+(?:\/[A-Za-z0-9._+ -]+)*\z/)
+        raise ArgumentError, "unsafe #{label}: #{value.inspect}"
+      end
+      path
+    end
+
+    def release_base_url
+      @release_base_url || @environment["ZUI_CLIENT_BASE_URL"] ||
+        "https://github.com/AdamMusa/zui/releases/download/v#{version}"
+    end
+
+    def cache_root
+      return File.expand_path(@cache_root) if @cache_root
+
+      override = @environment["ZUI_CACHE_HOME"]
+      return File.expand_path(override) if override && !override.empty?
+
+      home = @environment["HOME"] || @environment["USERPROFILE"] || Dir.home
+      if platform.windows?
+        @environment["LOCALAPPDATA"] || @environment["APPDATA"] || File.join(home, "AppData", "Local")
+      elsif platform.macos?
+        File.join(home, "Library", "Caches")
+      else
+        @environment["XDG_CACHE_HOME"] || File.join(home, ".cache")
+      end
+    end
+
+    def client_root_override?
+      value = @environment["ZUI_CLIENT_ROOT"]
+      value && !value.empty?
+    end
+
+  end
+end

data/lib/zui/components.rb

@@ -50,7 +50,6 @@ module Zui
     model_view_3d: [%i[source width height background rotation_x rotation_y rotation_z zoom minimum_zoom maximum_zoom interactive auto_rotate auto_rotate_speed reset_revision field_of_view camera_distance fit_size model_scale center_x center_y center_z key_light_color fill_light_color light_brightness antialiasing visible], %i[click double_click rotation_change zoom_change loaded error status], false],
     font_loader: [%i[source visible], %i[loaded error status], false],
     text_metrics: [%i[text font_family font_size bold italic letter_spacing word_spacing elide elide_width visible], %i[metrics], false],
-    web_view: [%i[url html base_url width height zoom_factor background_color active_focus_on_press javascript_enabled local_storage_enabled auto_load_images full_screen_support command command_revision visible], %i[load_start load_progress load_success load_failure url_change title_change navigation full_screen permission new_window error], false],
     animated_image: [%i[source width height fill_mode playing paused speed asynchronous cache mirror smooth visible], %i[frame loaded error status], false],
     video: [%i[source width height auto_play loops volume muted playback_rate fill_mode orientation mirrored visible], %i[play pause stop error position duration], false],
     audio: [%i[source auto_play playback position seek_revision loops volume muted playback_rate visible], %i[play pause stop end loaded status error position duration], false],

data/lib/zui/distribution.rb

@@ -7,20 +7,25 @@ module Zui
   class Distribution
     attr_reader :platform
 
-    def initialize(host: Host.new, platform: Platform.current, framework_root: FRAMEWORK_ROOT)
-      @host = host
+    def initialize(client: nil, platform: Platform.current, framework_root: FRAMEWORK_ROOT)
       @platform = platform.assert_supported!
+      @client = client || Client.new(platform: @platform)
       @framework_root = framework_root
     end
 
     def bundle(source, name: nil, destination: nil)
+      created = false
       project = File.expand_path(source)
       raise ArgumentError, "project directory not found: #{project}" unless File.directory?(project)
       raise ArgumentError, "main.rb not found: #{project}" unless File.file?(File.join(project, "main.rb"))
+      unless @client.configured?
+        raise ArgumentError, "Zui is not configured for #{platform.id}; run `zui doctor --fix` before bundling"
+      end
       app_name = name || titleize(File.basename(project))
       destination ||= default_destination(project, app_name)
       destination = File.expand_path(destination)
       raise ArgumentError, "bundle destination already exists: #{destination}" if File.exist?(destination)
+      created = true
 
       case platform.os
       when :linux then bundle_linux(project, destination, app_name)
@@ -29,19 +34,18 @@ module Zui
       end
       destination
     rescue StandardError
-      FileUtils.remove_entry(destination) if destination && File.exist?(destination)
+      FileUtils.remove_entry(destination) if created && destination && File.exist?(destination)
       raise
     end
 
     private
 
     def bundle_linux(project, destination, app_name)
-      FileUtils.mkdir_p([File.join(destination, "app"), File.join(destination, "bin"),
+      FileUtils.mkdir_p([File.join(destination, "app"),
                          File.join(destination, "runtime"), File.join(destination, "share", "applications")])
       install_application(project, File.join(destination, "app"))
       install_runtime(File.join(destination, "runtime"))
-      FileUtils.cp(@host.executable, File.join(destination, "bin", "zui-host"))
-      FileUtils.chmod(0o755, File.join(destination, "bin", "zui-host"))
+      @client.copy_to(File.join(destination, "runtime", "native"))
       write_linux_launcher(destination, app_name)
       desktop_name = "#{slug(app_name)}.desktop"
       File.write(File.join(destination, "share", "applications", desktop_name), <<~DESKTOP)
@@ -62,8 +66,7 @@ module Zui
       FileUtils.mkdir_p([macos, File.join(resources, "app"), File.join(resources, "runtime")])
       install_application(project, File.join(resources, "app"))
       install_runtime(File.join(resources, "runtime"))
-      FileUtils.cp(@host.executable, File.join(macos, "zui-host"))
-      FileUtils.chmod(0o755, File.join(macos, "zui-host"))
+      @client.copy_to(File.join(resources, "runtime", "native"))
       File.write(File.join(macos, "run"), macos_launcher(app_name))
       FileUtils.chmod(0o755, File.join(macos, "run"))
       File.write(File.join(contents, "Info.plist"), info_plist(app_name))
@@ -71,11 +74,11 @@ module Zui
     end
 
     def bundle_windows(project, destination, app_name)
-      FileUtils.mkdir_p([File.join(destination, "app"), File.join(destination, "bin"),
+      FileUtils.mkdir_p([File.join(destination, "app"),
                          File.join(destination, "runtime")])
       install_application(project, File.join(destination, "app"))
       install_runtime(File.join(destination, "runtime"))
-      FileUtils.cp(@host.executable, File.join(destination, "bin", "zui-host.exe"))
+      @client.copy_to(File.join(destination, "runtime", "native"))
       File.write(File.join(destination, "run.rb"), windows_ruby_launcher(app_name))
       File.write(File.join(destination, "run.cmd"), windows_command_launcher)
       write_manifest(destination, app_name)
@@ -93,7 +96,11 @@ module Zui
       Runtime.install_qml(File.join(destination, "qml"), framework_root: @framework_root)
       FileUtils.mkdir_p(File.join(destination, "lib"))
       FileUtils.cp(File.join(@framework_root, "lib", "zui.rb"), File.join(destination, "lib", "zui.rb"))
-      FileUtils.cp_r(File.join(@framework_root, "lib", "zui"), File.join(destination, "lib", "zui"))
+      source = File.join(@framework_root, "lib", "zui")
+      target = File.join(destination, "lib", "zui")
+      FileUtils.mkdir_p(target)
+      entries = Dir.children(source).reject { |entry| %w[client_builder.rb client_packager.rb].include?(entry) }
+      FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, target) unless entries.empty?
     end
 
     def write_linux_launcher(destination, app_name)
@@ -101,8 +108,10 @@ module Zui
         #!/bin/sh
         set -eu
         bundle_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+        native_dir="$bundle_dir/runtime/native"
+        #{posix_client_environment}
         ruby_command=${ZUI_RUBY:-ruby}
-        exec "$bundle_dir/bin/zui-host" \
+        exec "$native_dir/#{@client.executable_relative_path}" \
           --qml-root "$bundle_dir/runtime/qml" \
           --project "$bundle_dir/app" \
           --program "$bundle_dir/app/main.rb" \
@@ -119,8 +128,10 @@ module Zui
         set -eu
         contents=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
         resources="$contents/Resources"
+        native_dir="$resources/runtime/native"
+        #{posix_client_environment}
         ruby_command=${ZUI_RUBY:-ruby}
-        exec "$contents/MacOS/zui-host" \
+        exec "$native_dir/#{@client.executable_relative_path}" \
           --qml-root "$resources/runtime/qml" \
           --project "$resources/app" \
           --program "$resources/app/main.rb" \
@@ -137,8 +148,11 @@ module Zui
         require "rbconfig"
 
         bundle_dir = File.expand_path(__dir__)
+        native_dir = File.join(bundle_dir, "runtime", "native")
+        environment = {}
+        #{windows_environment_builder}
         arguments = [
-          File.join(bundle_dir, "bin", "zui-host.exe"),
+          File.join(native_dir, #{@client.executable_relative_path.dump}),
           "--qml-root", File.join(bundle_dir, "runtime", "qml"),
           "--project", File.join(bundle_dir, "app"),
           "--program", File.join(bundle_dir, "app", "main.rb"),
@@ -146,7 +160,7 @@ module Zui
           "--load-path", File.join(bundle_dir, "runtime", "lib"),
           "--name", #{app_name.to_s.dump}
         ]
-        exec(*arguments)
+        exec(environment, *arguments)
       RUBY
     end
 
@@ -183,7 +197,7 @@ module Zui
       File.write(File.join(directory, "zui-bundle.json"), JSON.pretty_generate(
         "format" => 1, "framework" => "zui", "version" => VERSION,
         "platform" => platform.os.to_s, "architecture" => platform.arch.to_s,
-        "name" => app_name
+        "name" => app_name, "client_version" => @client.manifest.fetch("client_version")
       ))
     end
 
@@ -196,5 +210,28 @@ module Zui
     def slug(value) = value.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
     def shell_quote(value) = "'#{value.to_s.gsub("'", %q('"'"'))}'"
     def xml_escape(value) = value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+
+    def posix_client_environment
+      @client.environment_entries.map do |name, paths|
+        value = paths.map { |path| "$native_dir/#{path}" }.join(":")
+        <<~SH.chomp
+          zui_environment="#{value}"
+          [ -z "${#{name}:-}" ] || zui_environment="$zui_environment:${#{name}}"
+          export #{name}="$zui_environment"
+        SH
+      end.join("\n")
+    end
+
+    def windows_client_environment = @client.environment_entries
+
+    def windows_environment_builder
+      @client.environment_entries.keys.map do |name|
+        <<~RUBY.chomp
+          values = #{windows_client_environment.fetch(name).inspect}.map { |path| File.join(native_dir, path) }
+          values << ENV[#{name.dump}] unless ENV[#{name.dump}].nil? || ENV[#{name.dump}].empty?
+          environment[#{name.dump}] = values.join(File::PATH_SEPARATOR)
+        RUBY
+      end.join("\n")
+    end
   end
 end

data/lib/zui/generator.rb

@@ -69,6 +69,7 @@ module Zui
         A native Linux, macOS, and Windows desktop application written in Ruby with Zui.
 
         ```bash
+        zui doctor --fix # once for each Zui version
         zui run main.rb
         zui bundle
         ```

data/lib/zui/host.rb

@@ -1,123 +1,45 @@
 # frozen_string_literal: true
 
-require "fileutils"
-require "tmpdir"
-
 module Zui
   class Host
-    attr_reader :platform
+    attr_reader :client, :platform
 
-    def initialize(platform: Platform.current, framework_root: FRAMEWORK_ROOT, environment: ENV)
+    def initialize(platform: Platform.current, environment: ENV, client: nil)
       @platform = platform.assert_supported!
-      @framework_root = framework_root
       @environment = environment
+      @client = client || Client.new(platform:, environment:)
     end
 
-    def executable(build: true)
+    def executable
       override = @environment["ZUI_HOST"]
       return checked_executable(override) if override && !override.empty?
-      return bundled if File.executable?(bundled)
-      return cached if File.executable?(cached)
-      return nil unless build
+      return client.executable if client.configured?
 
-      build!(cached)
+      raise ArgumentError, "Zui is not configured for #{platform.id}; run `zui doctor --fix`"
     end
 
-    def available? = !executable(build: false).nil?
-
-    def build!(destination = cached)
-      cmake = find_command("cmake")
-      raise ArgumentError, platform_help unless cmake
-
-      FileUtils.mkdir_p(File.dirname(destination))
-      Dir.mktmpdir("zui-host-build-") do |build_dir|
-        configure = Command.run([
-          cmake, "-S", File.join(@framework_root, "native"), "-B", build_dir,
-          "-DCMAKE_BUILD_TYPE=Release"
-        ], timeout: 180, max_output_bytes: 4_194_304)
-        raise ArgumentError, "Zui host configuration failed:\n#{configure.stderr}" unless configure.success?
-
-        compile = Command.run([cmake, "--build", build_dir, "--config", "Release", "--parallel"],
-                              timeout: 600, max_output_bytes: 8_388_608)
-        raise ArgumentError, "Zui host build failed:\n#{compile.stderr}" unless compile.success?
-
-        built = locate_build(build_dir)
-        raise ArgumentError, "Zui host build produced no executable" unless built
-        temporary = "#{destination}.install-#{Process.pid}"
-        FileUtils.cp(built, temporary)
-        FileUtils.chmod(0o755, temporary)
-        File.rename(temporary, destination)
-      ensure
-        FileUtils.rm_f(temporary) if temporary && File.exist?(temporary)
-      end
-      destination
-    end
+    def available?
+      override = @environment["ZUI_HOST"]
+      return File.executable?(File.expand_path(override)) if override && !override.empty?
 
-    def platform_help
-      if platform.macos?
-        "building Zui on macOS requires CMake and Qt 6 (for example: brew install cmake qt)"
-      elsif platform.windows?
-        "building Zui on Windows requires CMake, Qt 6, and a C++17 toolchain (Visual Studio Build Tools or LLVM/MinGW)"
-      else
-        "building Zui on Linux requires CMake, a C++17 compiler, and Qt 6 Core/Gui/Qml/Quick development packages"
-      end
+      client.configured?
     end
 
-    private
-
-    def bundled
-      File.join(@framework_root, "vendor", "host", platform.id, executable_name)
-    end
+    def configure! = client.configure!
 
-    def cached
-      cache_root = @environment["XDG_CACHE_HOME"]
-      cache_root = default_cache_root if cache_root.nil? || cache_root.empty?
-      File.join(cache_root, "zui", "host", VERSION, platform.id, executable_name)
-    end
+    def environment(base = ENV.to_h)
+      override = @environment["ZUI_HOST"]
+      return base.to_h.dup if override && !override.empty?
 
-    def default_cache_root
-      home = @environment["HOME"] || @environment["USERPROFILE"] || Dir.home
-      if platform.windows?
-        @environment["LOCALAPPDATA"] || @environment["APPDATA"] || File.join(home, "AppData", "Local")
-      elsif platform.macos?
-        File.join(home, "Library", "Caches")
-      else
-        File.join(home, ".cache")
-      end
+      client.environment(base)
     end
 
-    def executable_name = platform.os == :windows ? "zui-host.exe" : "zui-host"
+    private
 
     def checked_executable(path)
       expanded = File.expand_path(path)
       raise ArgumentError, "ZUI_HOST is not executable: #{expanded}" unless File.executable?(expanded)
       expanded
     end
-
-    def find_command(name)
-      @environment.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |directory|
-        command_names(name).each do |command_name|
-          path = File.join(directory, command_name)
-          return path if File.executable?(path) && !File.directory?(path)
-        end
-      end
-      nil
-    end
-
-    def command_names(name)
-      return [name] unless platform.windows? && File.extname(name).empty?
-
-      extensions = @environment.fetch("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";")
-      [name] + extensions.flat_map { |extension| ["#{name}#{extension.downcase}", "#{name}#{extension.upcase}"] }.uniq
-    end
-
-    def locate_build(build_dir)
-      candidates = [
-        File.join(build_dir, executable_name),
-        File.join(build_dir, "Release", executable_name),
-        File.join(build_dir, "zui-host.app", "Contents", "MacOS", "zui-host")
-      ]
-      candidates.find { |path| File.executable?(path) }
-    end
   end
 end