omarchy-ui 0.0.1-x86_64-linux

data/lib/omarchy_ui/cli.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "rbconfig"
+require "tmpdir"
+
+module OmarchyUI
+  class CLI
+    def self.run(arguments, out: $stdout, err: $stderr)
+      new(out:, err:).run(arguments)
+    end
+
+    def initialize(out:, err:)
+      @out = out
+      @err = err
+    end
+
+    def run(arguments)
+      command = arguments.shift
+      case command
+      when "run" then run_file(arguments)
+      when "launch" then launch_file(arguments)
+      when "new" then new_project(arguments)
+      when "bundle" then bundle_project(arguments)
+      when "push" then push(arguments)
+      when "validate" then validate(arguments)
+      when "version", "--version", "-v" then @out.puts(OmarchyUI::VERSION); 0
+      else
+        @err.puts("Usage: omarchy_ui <new NAME|run FILE|launch FILE|bundle [DIRECTORY]|push [DIRECTORY]|validate [DIRECTORY]|version>")
+        command.nil? ? 0 : 64
+      end
+    rescue ArgumentError, SystemCallError, JSON::ParserError => error
+      @err.puts("omarchy_ui: #{error.message}")
+      1
+    end
+
+    private
+
+    def run_file(arguments)
+      file = File.expand_path(arguments.shift || raise(ArgumentError, "run requires a Ruby file"))
+      raise ArgumentError, "Ruby file not found: #{file}" unless File.file?(file)
+      exec(RbConfig.ruby, "-I", File.join(FRAMEWORK_ROOT, "lib"), file, *arguments)
+    end
+
+    def launch_file(arguments)
+      file = File.expand_path(arguments.shift || raise(ArgumentError, "launch requires a Ruby file"))
+      raise ArgumentError, "Ruby file not found: #{file}" unless File.file?(file)
+      raise ArgumentError, "launch does not accept Ruby arguments" unless arguments.empty?
+
+      project_dir = File.dirname(file)
+      Dir.mktmpdir("omarchy-ui-app-") do |runtime_dir|
+        Project::RUNTIME_FILES.each do |name|
+          source = File.file?(File.join(project_dir, name)) ? File.join(project_dir, name) : File.join(FRAMEWORK_ROOT, name)
+          FileUtils.cp(source, runtime_dir)
+        end
+        %w[Commons Ui].each do |module_name|
+          source = File.join("/usr/share/omarchy/shell", module_name)
+          raise ArgumentError, "Omarchy QML module not found: #{source}" unless File.directory?(source)
+          FileUtils.ln_s(source, File.join(runtime_dir, module_name))
+        end
+
+        environment = ENV.to_h.merge(
+          "OMARCHY_UI_PROJECT_DIR" => project_dir,
+          "OMARCHY_UI_RUBY_PROGRAM" => file,
+          "OMARCHY_UI_RUNTIME" => Runtime.executable
+        )
+        success = system(environment, "quickshell", "--path", File.join(runtime_dir, "App.qml"))
+        return success ? 0 : ($?&.exitstatus || 1)
+      end
+    end
+
+    def new_project(arguments)
+      name = arguments.shift || raise(ArgumentError, "new requires a project name")
+      raise ArgumentError, "new accepts only an application name" unless arguments.empty?
+      destination = File.expand_path(slug(name))
+      Project.new(path: destination, name: name).create
+      @out.puts("Created standalone Omarchy UI app in #{destination}")
+      0
+    end
+
+    def slug(value)
+      result = value.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|\-\z/, "")
+      raise ArgumentError, "name must contain letters or numbers" if result.empty?
+      result
+    end
+
+    def validate(arguments)
+      source = File.expand_path(arguments.shift || Dir.pwd)
+      with_staged_project(source) do |staging|
+        system("omarchy", "plugin", "validate", staging) ? 0 : 1
+      end
+    end
+
+    def bundle_project(arguments)
+      source = File.expand_path(arguments.shift || Dir.pwd)
+      raise ArgumentError, "bundle accepts one directory" unless arguments.empty?
+      raise ArgumentError, "main.rb not found: #{source}" unless File.file?(File.join(source, "main.rb"))
+      destination = File.join(source, "dist", File.basename(source))
+      raise ArgumentError, "bundle destination already exists: #{destination}" if File.exist?(destination)
+      FileUtils.mkdir_p(destination)
+      entries = Dir.children(source).reject { |entry| %w[.git dist].include?(entry) }
+      FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, destination)
+      Project.install_runtime(destination)
+      runtime = File.join(destination, "omarchy-ui-runtime")
+      FileUtils.cp(Runtime::BUNDLED, runtime)
+      FileUtils.chmod(0o755, runtime)
+      %w[Commons Ui].each do |module_name|
+        FileUtils.ln_s(File.join("/usr/share/omarchy/shell", module_name), File.join(destination, module_name))
+      end
+      launcher = File.join(destination, "run")
+      File.write(launcher, <<~SH)
+        #!/bin/sh
+        set -eu
+        app_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+        export OMARCHY_UI_RUNTIME="$app_dir/omarchy-ui-runtime"
+        export OMARCHY_UI_PROJECT_DIR="$app_dir"
+        export OMARCHY_UI_RUBY_PROGRAM="$app_dir/main.rb"
+        exec quickshell --path "$app_dir/App.qml"
+      SH
+      FileUtils.chmod(0o755, launcher)
+      @out.puts("Bundled application in #{destination}")
+      0
+    rescue StandardError
+      FileUtils.remove_entry(destination) if destination && File.directory?(destination)
+      raise
+    end
+
+    def push(arguments)
+      enable = !arguments.delete("--no-enable")
+      restart = !arguments.delete("--no-restart")
+      source = File.expand_path(arguments.shift || Dir.pwd)
+      Runtime.install_shared
+      manifest_path = File.join(source, "manifest.json")
+      manifest = JSON.parse(File.read(manifest_path))
+      plugin_id = manifest.fetch("id")
+      raise ArgumentError, "invalid plugin id" unless VALID_ID.match?(plugin_id)
+      plugin_root = File.expand_path("~/.config/omarchy/plugins")
+      backup_root = File.expand_path("~/.local/state/omarchy-ui/backups")
+      destination = File.join(plugin_root, plugin_id)
+      raise ArgumentError, "cannot push an installed plugin onto itself" if source == destination
+      FileUtils.mkdir_p(plugin_root)
+      backup = nil
+      staging = stage_project(source, parent: plugin_root, prefix: ".#{plugin_id}.staging-")
+      raise ArgumentError, "staged plugin validation failed" unless system("omarchy", "plugin", "validate", staging)
+
+      if File.exist?(destination)
+        FileUtils.mkdir_p(backup_root)
+        backup = File.join(backup_root, "#{plugin_id}-#{Time.now.strftime('%Y%m%d%H%M%S')}-#{Process.pid}")
+        FileUtils.mv(destination, backup)
+        @out.puts("Backed up existing plugin to #{backup}")
+      end
+      FileUtils.mv(staging, destination)
+      staging = nil
+      activate_plugin(plugin_id) if enable
+      raise ArgumentError, "shell restart failed; plugin is installed but not active" if restart && !system("omarchy", "restart", "shell")
+      @out.puts("Pushed #{plugin_id} to #{destination}")
+      0
+    rescue StandardError
+      if backup && !File.exist?(destination) && File.exist?(backup)
+        FileUtils.mv(backup, destination)
+        @err.puts("Restored previous plugin after push failure")
+      end
+      raise
+    ensure
+      FileUtils.remove_entry(staging) if staging && File.exist?(staging)
+    end
+
+    def with_staged_project(source)
+      staging = stage_project(source)
+      yield staging
+    ensure
+      FileUtils.remove_entry(staging) if staging && File.exist?(staging)
+    end
+
+    def stage_project(source, parent: nil, prefix: ".omarchy-ui-staging-")
+      raise ArgumentError, "project directory not found: #{source}" unless File.directory?(source)
+      staging = parent ? Dir.mktmpdir(prefix, parent) : Dir.mktmpdir(prefix)
+      entries = Dir.children(source).reject { |entry| entry == ".git" }
+      FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, staging) unless entries.empty?
+      Project.install_runtime(staging) if File.file?(File.join(staging, "main.rb"))
+      staging
+    rescue StandardError
+      FileUtils.remove_entry(staging) if staging && File.exist?(staging)
+      raise
+    end
+
+    def activate_plugin(plugin_id)
+      return if system("omarchy", "plugin", "enable", plugin_id)
+      system("omarchy-shell", "shell", "rescanPlugins")
+      20.times do
+        return if system("omarchy", "plugin", "enable", plugin_id, out: File::NULL, err: File::NULL)
+        sleep(0.1)
+      end
+      raise ArgumentError, "plugin was installed but Omarchy could not enable #{plugin_id}"
+    end
+  end
+end

data/lib/omarchy_ui/command.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module OmarchyUI
+  class CommandTimeout < StandardError; end
+
+  CommandResult = Struct.new(:stdout, :stderr, :status, keyword_init: true) do
+    def success? = status.success?
+    def exitstatus = status.exitstatus
+  end
+
+  module Command
+    module_function
+
+    def run(argv, env: {}, chdir: nil, input: "", timeout: nil)
+      arguments = normalize_argv(argv)
+      options = {}
+      options[:chdir] = File.expand_path(chdir) if chdir
+      stdin = stdout = stderr = wait_thread = nil
+      Open3.popen3(normalize_env(env), *arguments, **options) do |child_stdin, child_stdout, child_stderr, child_wait|
+        stdin, stdout, stderr, wait_thread = child_stdin, child_stdout, child_stderr, child_wait
+        stdin.write(input.to_s)
+        stdin.close
+        stdout_reader = Thread.new { stdout.read }
+        stderr_reader = Thread.new { stderr.read }
+        status = timeout ? Timeout.timeout(Float(timeout)) { wait_thread.value } : wait_thread.value
+        return CommandResult.new(stdout: stdout_reader.value, stderr: stderr_reader.value, status:)
+      rescue Timeout::Error
+        terminate(wait_thread)
+        stdout_reader&.join(1)
+        stderr_reader&.join(1)
+        raise CommandTimeout, "command timed out after #{timeout}s: #{arguments.first}"
+      end
+    ensure
+      [stdin, stdout, stderr].each { |stream| stream&.close unless stream&.closed? }
+    end
+
+    def normalize_argv(argv)
+      raise ArgumentError, "command must be an argv array" unless argv.is_a?(Array) && !argv.empty?
+      argv.map do |argument|
+        raise ArgumentError, "command arguments must be strings" unless argument.is_a?(String)
+        raise ArgumentError, "command arguments cannot contain NUL" if argument.include?("\0")
+        argument
+      end
+    end
+    private_class_method :normalize_argv
+
+    def normalize_env(env)
+      raise ArgumentError, "command environment must be a hash" unless env.is_a?(Hash)
+      env.to_h { |key, value| [key.to_s, value.to_s] }
+    end
+    private_class_method :normalize_env
+
+    def terminate(wait_thread)
+      Process.kill("TERM", wait_thread.pid)
+      Timeout.timeout(1) { wait_thread.value }
+    rescue Errno::ESRCH, Errno::ECHILD
+      nil
+    rescue Timeout::Error
+      Process.kill("KILL", wait_thread.pid)
+      wait_thread.value
+    end
+    private_class_method :terminate
+  end
+end

data/lib/omarchy_ui/component_registry.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module OmarchyUI
+  Component = Struct.new(:name, :qml, :properties, :events, :property_map, :event_map, :container, :auto_bind, keyword_init: true) do
+    def to_h
+      {
+        "qml" => qml,
+        "properties" => properties.map(&:to_s),
+        "events" => events.map(&:to_s),
+        "property_map" => property_map.transform_keys(&:to_s).transform_values(&:to_s),
+        "event_map" => event_map.transform_keys(&:to_s).transform_values(&:to_s),
+        "container" => container,
+        "auto_bind" => auto_bind
+      }
+    end
+  end
+
+  class ComponentRegistry
+    QML_FILE = Object.new
+    def QML_FILE.match?(value)
+      text = value.to_s
+      stem = text.end_with?(".qml") ? text[0...-4] : ""
+      !stem.empty? && OmarchyUI::UPPER.include?(stem[0]) && stem.each_char.all? do |character|
+        (OmarchyUI::LOWER + OmarchyUI::UPPER + OmarchyUI::DIGITS).include?(character)
+      end
+    end
+    NAME = AsciiPattern.new(min: 1, max: 64, first: LOWER, rest: LOWER + DIGITS + "_")
+    ITEM_PROPERTIES = %i[visible enabled opacity scale rotation z width height].freeze
+
+    def initialize
+      @components = {}
+    end
+
+    def register(name, qml:, properties: [], events: [], property_map: {}, event_map: {}, container: false, auto_bind: true)
+      key = name.to_sym
+      raise ArgumentError, "component already registered: #{key}" if @components.key?(key)
+      raise ArgumentError, "invalid component name: #{name.inspect}" unless NAME.match?(key.to_s)
+      raise ArgumentError, "invalid component adapter: #{qml.inspect}" unless QML_FILE.match?(qml.to_s)
+      property_names = (properties.map(&:to_sym) + property_map.keys.map(&:to_sym) + ITEM_PROPERTIES).uniq
+      event_names = (events.map(&:to_sym) + event_map.keys.map(&:to_sym)).uniq
+      normalized_property_map = properties.to_h { |property| [property.to_sym, property.to_sym] }
+      normalized_property_map.merge!(property_map.to_h { |key, value| [key.to_sym, value.to_sym] })
+      normalized_event_map = events.to_h { |event| [event.to_sym, event.to_sym] }
+      normalized_event_map.merge!(event_map.to_h { |key, value| [key.to_sym, value.to_sym] })
+      invalid_property = property_names.find { |property| !NAME.match?(property.to_s) }
+      invalid_event = event_names.find { |event| !NAME.match?(event.to_s) }
+      raise ArgumentError, "invalid property name: #{invalid_property.inspect}" if invalid_property
+      raise ArgumentError, "invalid event name: #{invalid_event.inspect}" if invalid_event
+      invalid_target = (normalized_property_map.values + normalized_event_map.values).find { |target| !NAME.match?(target.to_s) }
+      raise ArgumentError, "invalid QML member name: #{invalid_target.inspect}" if invalid_target
+
+      @components[key] = Component.new(
+        name: key,
+        qml: qml.to_s,
+        properties: property_names.uniq.freeze,
+        events: event_names.uniq.freeze,
+        property_map: normalized_property_map.freeze,
+        event_map: normalized_event_map.freeze,
+        container: !!container,
+        auto_bind: !!auto_bind
+      )
+    end
+
+    def fetch(name)
+      @components.fetch(name.to_sym) { raise ArgumentError, "unknown component: #{name}" }
+    end
+
+    def key?(name)
+      @components.key?(name.to_sym)
+    end
+
+    def protocol_schema
+      @components.transform_keys(&:to_s).transform_values(&:to_h)
+    end
+
+    def dup
+      copy = self.class.new
+      @components.each_value do |component|
+        copy.register(component.name, qml: component.qml, properties: component.properties,
+                       events: component.events, property_map: component.property_map,
+                       event_map: component.event_map, container: component.container,
+                       auto_bind: component.auto_bind)
+      end
+      copy
+    end
+  end
+end

data/lib/omarchy_ui/components.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module OmarchyUI
+  COMPONENTS = {
+    container: [%i[spacing padding bordered visible], %i[click], true],
+    row: [%i[spacing alignment visible], %i[click], true],
+    column: [%i[spacing alignment visible], %i[click], true],
+    grid: [%i[columns rows spacing row_spacing column_spacing visible], %i[click], true],
+    stack: [%i[visible], %i[click], true],
+    scroll: [%i[width height clip visible], %i[click], true],
+    rectangle: [%i[width height color radius border_color border_width padding visible], %i[click], true],
+    text: [%i[text style size bold color wrap width visible], [], false],
+    icon: [%i[name text size color visible], [], false],
+    image: [%i[source width height fill_mode visible], [], false],
+    spacer: [%i[width height visible], [], false],
+    button: [%i[text icon tooltip selected active cursor focusable bordered foreground background accent font_family font_size icon_size icon_rotation icon_spinning horizontal_padding vertical_padding left_align tooltip_background tooltip_foreground tooltip_border], %i[click right_click hover], false],
+    action_button: [%i[icon tooltip foreground hover_color font_family font_size size focusable cursor bordered], %i[click hover], false],
+    toggle: [%i[label description checked cursor rounded foreground accent font_family title_size description_size], %i[change hover], false],
+    toggle_switch: [%i[checked busy interactive cursor cursor_ring cursor_pad rounded foreground accent track_height track_width knob_size knob_inset], %i[change hover], false],
+    text_field: [%i[text placeholder password foreground accent selection_tint horizontal_padding vertical_padding cursor], %i[change submit focus blur input], false],
+    number_field: [%i[label value from to step foreground accent font_family font_size field_width cursor], %i[change hover], false],
+    slider: [%i[value minimum maximum step integer track_color fill_color knob_color track_height knob_size ticks tick_color], %i[input change right_click], false],
+    dropdown: [%i[label value options foreground background popup_border accent font_family row_height popup_row_height show_label cursor], %i[change hover], false],
+    searchable_dropdown: [%i[label value options placeholder empty_text trigger_label foreground background popup_border accent font_family row_height popup_row_height popup_min_height show_label cursor], %i[change hover], false],
+    multi_select: [%i[label values options options_command options_command_cwd placeholder empty_text no_selection_text trigger_label show_label foreground background popup_border accent font_family row_height popup_row_height popup_min_height cursor], %i[change hover], false],
+    button_group: [%i[value options foreground background accent font_family font_size focusable cursor_index], %i[change hover], false],
+    progress: [%i[value minimum maximum width height color visible], [], false],
+    separator: [%i[strength visible], [], false],
+    section_header: [%i[text visible], [], false],
+    confirm_dialog: [%i[opened message cancel_text confirm_text selected_index background foreground scrim selected_background selected_text font_family corner_radius], %i[cancel confirm], false],
+    panel_hero: [%i[title meta detail foreground font_family icon_size icon_opacity meta_opacity], [], false],
+    optical_glyph: [%i[text size color debug_bounds visible], [], false],
+    cursor_surface: [%i[cursor current outline bordered foreground accent fill current_fill], %i[click], true],
+    widget_button: [%i[text font_family font_size foreground active_color active horizontal_margin vertical_padding fixed_width fixed_height text_rotation keep_space dimmed concealed interactive pressable use_active_color maintain_indicator_reveal label_visible has_visual_content tooltip], %i[click right_click middle_click wheel], false],
+    list_view: [%i[items key_field label_field description_field icon_field selected orientation spacing width height empty_text visible], %i[activate change scroll], false]
+  }.freeze
+
+  DEFAULT_COMPONENTS = ComponentRegistry.new
+  COMPONENTS.each do |name, (properties, events, container)|
+    adapter = name.to_s.split("_").map(&:capitalize).join + ".qml"
+    DEFAULT_COMPONENTS.register(name, qml: adapter, properties:, events:, container:)
+  end
+end

data/lib/omarchy_ui/node.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OmarchyUI
+  class Node
+    attr_reader :type, :id, :props, :children, :events
+
+    def initialize(type:, id:, props: {})
+      @type = type.to_s
+      @id = id.to_s
+      @props = props.transform_keys(&:to_s)
+      @children = []
+      @events = []
+    end
+
+    def to_h
+      result = { "type" => type, "id" => id }
+      result["props"] = props unless props.empty?
+      result["children"] = children.map(&:to_h) unless children.empty?
+      result["events"] = events unless events.empty?
+      result
+    end
+
+    def subscribe(event)
+      @events << event.to_s unless @events.include?(event.to_s)
+    end
+  end
+
+  Binding = Struct.new(:node, :property, :reader, :last_value, :animation, keyword_init: true)
+  StructuralBinding = Struct.new(:node, :renderer, :last_children, keyword_init: true)
+end

data/lib/omarchy_ui/project.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OmarchyUI
+  class Project
+    RUNTIME_FILES = %w[Service.qml ControlNode.qml Panel.qml BarWidget.qml App.qml].freeze
+
+    def initialize(path:, name: nil, framework_root: FRAMEWORK_ROOT)
+      @path = File.expand_path(path)
+      @name = name || File.basename(@path).split(/[-_]/).map(&:capitalize).join(" ")
+      @framework_root = framework_root
+    end
+
+    def create
+      raise ArgumentError, "destination already exists: #{@path}" if File.exist?(@path)
+      created = true
+      FileUtils.mkdir_p(File.join(@path, "Components"))
+      File.write(File.join(@path, "main.rb"), main_program)
+      File.write(File.join(@path, "Components", "Welcome.qml"), welcome_component)
+      File.write(File.join(@path, "README.md"), readme)
+      @path
+    rescue StandardError
+      FileUtils.remove_entry(@path) if created && File.directory?(@path)
+      raise
+    end
+
+    def self.install_runtime(path, framework_root: FRAMEWORK_ROOT)
+      RUNTIME_FILES.each do |file|
+        destination = File.join(path, file)
+        FileUtils.cp(File.join(framework_root, file), destination) unless File.exist?(destination)
+      end
+      bundled_runtime = File.join(framework_root, "vendor", "runtime", "x86_64-linux", "omarchy-ui-runtime")
+      if File.file?(bundled_runtime)
+        destination = File.join(path, "omarchy-ui-runtime")
+        FileUtils.cp(bundled_runtime, destination)
+        FileUtils.chmod(0o755, destination)
+      end
+      FileUtils.mkdir_p(File.join(path, "Components"))
+    end
+
+    private
+
+    def main_program
+      <<~RUBY
+        # frozen_string_literal: true
+
+        require "omarchy_ui" unless Object.const_defined?(:OmarchyUI)
+
+        OmarchyUI.plugin do
+          register_component :welcome,
+            qml: "Welcome.qml",
+            properties: %i[title message]
+
+          app :main, title: "#{@name}", width: 760, height: 520 do
+            component :welcome,
+              title: "Welcome to #{@name}",
+              message: "This is the official Omarchy UI framework."
+          end
+        end
+      RUBY
+    end
+
+    def welcome_component
+      <<~QML
+        import QtQuick
+        import qs.Commons
+        import qs.Ui
+
+        BorderSurface {
+          id: root
+
+          property string title: "Welcome"
+          property string message: "This is the official Omarchy UI framework."
+
+          implicitWidth: 520
+          implicitHeight: 220
+          color: Color.popups.background
+          radius: Style.cornerRadius
+          borderSpec: Border.controlSpec("normal", Color.foreground, Color.accent)
+
+          Column {
+            anchors.centerIn: parent
+            spacing: Style.spacing.lg
+
+            Text {
+              anchors.horizontalCenter: parent.horizontalCenter
+              text: root.title
+              color: Color.foreground
+              font.family: Style.font.family
+              font.pixelSize: Style.font.heading
+              font.bold: true
+            }
+
+            Text {
+              anchors.horizontalCenter: parent.horizontalCenter
+              text: root.message
+              color: Color.foreground
+              font.family: Style.font.family
+              font.pixelSize: Style.font.body
+            }
+          }
+        }
+      QML
+    end
+
+    def readme
+      <<~MARKDOWN
+        # #{@name}
+
+        A standalone application built with the official Omarchy UI framework.
+
+        ## Run
+
+        ```bash
+        omarchy_ui launch main.rb
+        ```
+
+        The shared `omarchy-ui-runtime` must be installed on `PATH`. No system Ruby,
+        application manifest, or copied framework QML files are required.
+
+        Edit `main.rb` for application state and behavior. Custom QML adapters live in
+        `Components/`; `Welcome.qml` is included as a working example.
+      MARKDOWN
+    end
+  end
+end

data/lib/omarchy_ui/protocol.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OmarchyUI
+  PROTOCOL_VERSION = 1
+  MAX_MESSAGE_BYTES = 1_048_576
+  class AsciiPattern
+    def initialize(min:, max:, first: nil, rest:)
+      @min = min
+      @max = max
+      @first = first
+      @rest = rest
+    end
+
+    def match?(value)
+      text = value.to_s
+      return false if text.length < @min || text.length > @max
+      return false if @first && !@first.include?(text[0])
+      text.each_char.all? { |character| @rest.include?(character) }
+    end
+  end
+
+  LOWER = ("a".."z").to_a.join.freeze
+  UPPER = ("A".."Z").to_a.join.freeze
+  DIGITS = ("0".."9").to_a.join.freeze
+  VALID_ID = AsciiPattern.new(min: 1, max: 128, rest: LOWER + UPPER + DIGITS + "_.:-")
+  VALID_EVENT = AsciiPattern.new(min: 1, max: 64, first: LOWER, rest: LOWER + DIGITS + "_")
+
+  class ProtocolError < StandardError; end
+end

data/lib/omarchy_ui/runtime.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OmarchyUI
+  module Runtime
+    module_function
+
+    BUNDLED = File.expand_path("../../vendor/runtime/x86_64-linux/omarchy-ui-runtime", __dir__)
+
+    def executable
+      override = ENV["OMARCHY_UI_RUNTIME"]
+      return File.expand_path(override) if override && !override.empty?
+      return BUNDLED if File.executable?(BUNDLED)
+      "omarchy-ui-runtime"
+    end
+
+    def install_shared(destination: nil)
+      destination ||= File.expand_path("~/.local/bin/omarchy-ui-runtime")
+      raise ArgumentError, "bundled mruby runtime is missing" unless File.file?(BUNDLED)
+      FileUtils.mkdir_p(File.dirname(destination))
+      temporary = "#{destination}.install-#{Process.pid}"
+      FileUtils.cp(BUNDLED, temporary)
+      FileUtils.chmod(0o755, temporary)
+      File.rename(temporary, destination)
+      destination
+    ensure
+      FileUtils.rm_f(temporary) if temporary && File.exist?(temporary)
+    end
+  end
+end