omarchy-ui 0.0.9-x86_64-linux → 0.0.10-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82c12f3f51c0d9242be7386a4994c4f3fe8b333d04489e4055b671054cb2f0e2
-  data.tar.gz: e693d5b68a5ad055b40fbb910b4bb6ef41b6de7405027396305f256ad744875d
+  metadata.gz: ba33f1f0b7fead5be0f82726faeeb3815b94386f679732ee4945d840374a1023
+  data.tar.gz: bc7bfb798a46491d22085e3f81cbde27da3b9f14149b1ec63bd3e36b182f83c7
 SHA512:
-  metadata.gz: 807cb5e30c33130681351065bc7fce902a7c4c125f1c6b47e8827db0ec6b49695745ab60d61da9475153f8abf1422940df280154af797ede39ef218a9097c449
-  data.tar.gz: c2f3532f53a5725e7c6e7cd9de667ebbb2dddd086204af8172f8b262c010e4fef2470b73716a7496c9859d396f43b22814e03926949944e2e1c080e1e64ca5a2
+  metadata.gz: c76b00784fdf4a0371269d79d570e10ece613faf94449f2e40025a7a5a7a45b53080b259a7a68cedc7e21c89cc03e628cc3e3301c04db806145db19cc2b0d6ed
+  data.tar.gz: f4511e5523b4a033be1d80682305d99e0502721186cf8330d3c4d10e332bf0e85233d96f1b59840c54f7679e34abe4b8018b170357170b1bff6e1e38f4f697e6

data/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  <img alt="Omarchy UI 0.0.9" src="https://img.shields.io/badge/Omarchy_UI-0.0.9-b7ff5a?style=flat-square&labelColor=111711">
+  <img alt="Omarchy UI 0.0.10" src="https://img.shields.io/badge/Omarchy_UI-0.0.10-b7ff5a?style=flat-square&labelColor=111711">
   <img alt="Ruby 3.1 or newer" src="https://img.shields.io/badge/Ruby-3.1%2B-cc342d?style=flat-square&logo=ruby&logoColor=white">
   <img alt="Zui 0.0.10" src="https://img.shields.io/badge/Zui-0.0.10-7ee14b?style=flat-square&labelColor=111711">
   <img alt="241 components" src="https://img.shields.io/badge/components-241-75d943?style=flat-square&labelColor=111711">
@@ -294,6 +294,19 @@ omarchy_ui push
 `validate` generates and checks the plugin without modifying the Ruby project. `push` builds,
 validates, installs, enables, and reloads it for development.
 
+To publish, target a separate public distribution repository. Omarchy UI rebuilds the thin package,
+enforces the marketplace contract, pushes it, and prints the complete submission for review:
+
+```bash
+omarchy_ui publish --repo YOUR_GITHUB_NAME/PLUGIN_REPOSITORY \
+  --category System --tags system,quickshell --create
+```
+
+After reviewing the printed title, metadata, and five marketplace attestations, rerun the same
+command with `--submit`. It creates a submission or refreshes an existing open one. This two-step
+flow prevents accidental replacement of the source repository and ensures the ownership statement
+is reviewed before it is posted.
+
 During development, suppress either lifecycle action when needed:
 
 ```bash
@@ -310,9 +323,10 @@ omarchy_ui <command> [arguments]
 | Command | Arguments | Result |
 | --- | --- | --- |
 | `omarchy_ui new NAME` | One project name | Creates an Omarchy application project |
-| `omarchy_ui new NAME --plugin` | One project name and `--plugin` | Creates an Omarchy plugin project |
+| `omarchy_ui new NAME --plugin --github USER` | One project name, `--plugin`, and optional GitHub user | Creates a marketplace-ready Omarchy plugin project |
 | `omarchy_ui run FILE` | One Ruby entry point | Runs an application through the Omarchy/Quickshell host |
 | `omarchy_ui bundle [DIRECTORY]` | Zero or one project directory | Generates the distributable package and prints its location |
+| `omarchy_ui publish [DIRECTORY]` | Required `--repo`, `--category`, `--tags`; optional `--create`, `--submit` | Builds and pushes a thin distribution repository, then previews or submits its marketplace issue |
 | `omarchy_ui validate [DIRECTORY]` | Zero or one plugin directory | Stages the plugin and delegates validation to `omarchy plugin validate` |
 | `omarchy_ui push [DIRECTORY]` | Optional `--no-enable` and `--no-restart` | Atomically installs and activates a validated plugin |
 | `omarchy_ui version` | None | Prints the installed Omarchy UI version |
@@ -328,20 +342,20 @@ Create the distributable package from the project root:
 omarchy_ui bundle
 ```
 
-Omarchy UI assembles the Ruby source and assets, Omarchy entry points, native host, checksummed
-runtime, and only the Zui components used by the project. It then AOT-compiles the generated QML into
-a content-addressed Qt module and discards the generated component, control, theme, and font source
-tree. Applications receive a direct launcher; plugins must pass Omarchy validation before the
-command succeeds. Omarchy UI pins Zui 0.0.10 so the compiled UI matches the Zui core embedded in the
-deterministic mruby runtime.
-
-Current Omarchy manifests resolve entry points by filename, so a package retains four minimal loader
-files: `App.qml`, `Service.qml`, `Panel.qml`, and `BarWidget.qml`. They contain only an import and a
-compiled type instance; the application interface is stored in native `.so` artifacts. The package
-also includes `omarchy-ui-qml-bundle.json` with the module URI and exact Qt version, plus
-`omarchy-ui-qml-bundle.sha256` for artifact verification. `QML_PROVENANCE.md` explains the native
-artifacts for package reviewers. Compiled packages should be built against the Qt version shipped by
-their target Omarchy release.
+Omarchy UI assembles one bundled Ruby program and required assets, native runtime, manifest, and only
+the Zui components used by the project. It AOT-compiles the generated QML into a content-addressed Qt
+module, then discards the generated component, control, theme, and font source tree. Applications
+receive a direct launcher; plugins must pass Omarchy validation before the command succeeds. Omarchy
+UI pins Zui 0.0.10 so the compiled UI matches the Zui core embedded in the deterministic mruby
+runtime.
+
+Current Omarchy entry points resolve by filename, so a package retains only the required generated
+loader shims. Applications keep `App.qml`; standard plugins keep `Service.qml`, `Panel.qml`, and
+`BarWidget.qml`. Each shim contains only an import and a compiled type instance. The application
+interface is authored in Ruby and stored in native `.so` artifacts. Distributable packages do not
+include generated QML source, build reports, audit/provenance folders, checksums, tests, or CI files.
+They also omit `config.rb` and Ruby files already folded into `main.rb`.
+Compiled packages should be built against the Qt version shipped by their target Omarchy release.
 
 The source `config.rb` is the build configuration. Omarchy UI generates plugin manifests from it;
 developers never maintain a separate manifest.
@@ -416,7 +430,7 @@ Omarchy process bridge ───────────────── embed
           ▼
 Tree-shaken Zui host + component catalog
           │
-          │ bundle: Qt AOT module + four loader shims
+          │ bundle: Qt AOT module + required loader shims
           │
           ▼
 App window · Omarchy panel · Omarchy bar widget

data/Service.qml

@@ -499,4 +499,27 @@ Item {
     repeat: false
     onTriggered: root.startRuby()
   }
+
+  // A desktop surface is rendered by the same long-lived service that owns
+  // the Ruby runtime. Its DesktopStage adapter creates the layer-shell window;
+  // plugins keep all scene structure, state, and interaction in Ruby.
+  ControlNode {
+    id: desktopRenderer
+    visible: root.ready && root.rootId("desktop") !== ""
+    bridge: root
+    surfaceName: "desktop"
+    controlId: root.rootId(surfaceName)
+  }
+
+  IpcHandler {
+    target: root.manifest && root.manifest.id ? String(root.manifest.id) : "omarchy-ui"
+
+    function playPause(): string {
+      var desktopId = root.rootId("desktop")
+      if (desktopId === "") return "not-ready"
+      return root.sendEvent("desktop", desktopId, "shortcut", { name: "play_pause" })
+        ? "ok"
+        : "not-ready"
+    }
+  }
 }

data/lib/omarchy_ui/cli.rb

@@ -23,11 +23,12 @@ module OmarchyUI
       when "run" then run_file(arguments)
       when "new" then new_project(arguments)
       when "bundle" then bundle_project(arguments)
+      when "publish" then publish(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 [--plugin]|run FILE|bundle [DIRECTORY]|push [DIRECTORY]|validate [DIRECTORY]|version>")
+        @err.puts("Usage: omarchy_ui <new NAME [--plugin] [--github USER]|run FILE|bundle [DIRECTORY]|publish [DIRECTORY] --repo OWNER/REPO --category CATEGORY --tags TAGS [--create] [--submit]|push [DIRECTORY]|validate [DIRECTORY]|version>")
         command.nil? ? 0 : 64
       end
     rescue Interrupt
@@ -68,11 +69,14 @@ module OmarchyUI
 
     def new_project(arguments)
       plugin = !arguments.delete("--plugin").nil?
+      github_user = extract_option!(arguments, "--github")
       name = arguments.shift || raise(ArgumentError, "new requires a project name")
-      raise ArgumentError, "new accepts a name and optional --plugin" unless arguments.empty?
+      raise ArgumentError, "new accepts a name, --plugin, and --github USER" unless arguments.empty?
+      raise ArgumentError, "--github is only valid with --plugin" if github_user && !plugin
       destination = File.expand_path(slug(name))
       kind = plugin ? :plugin : :application
-      Generator.new(path: destination, name: name, kind:, author: default_author).create
+      github_user ||= default_github_user if plugin
+      Generator.new(path: destination, name: name, kind:, author: default_author, github_user:).create
       label = plugin ? "Omarchy-compliant plugin" : "self-contained Omarchy application"
       @out.puts("Created #{label} in #{destination}")
       0
@@ -91,6 +95,30 @@ module OmarchyUI
       "Omarchy UI Developer"
     end
 
+    def default_github_user
+      configured = ENV["OMARCHY_UI_GITHUB_USER"].to_s.strip
+      return configured unless configured.empty?
+
+      output, _error, status = Open3.capture3("gh", "api", "user", "--jq", ".login")
+      login = output.to_s.strip
+      return login if status.success? && !login.empty?
+
+      raise ArgumentError,
+        "plugin generation needs --github USER or OMARCHY_UI_GITHUB_USER (gh auth login can provide it automatically)"
+    rescue Errno::ENOENT
+      raise ArgumentError, "plugin generation needs --github USER or OMARCHY_UI_GITHUB_USER"
+    end
+
+    def extract_option!(arguments, name)
+      index = arguments.index(name)
+      return nil unless index
+
+      value = arguments[index + 1]
+      raise ArgumentError, "#{name} requires a value" if value.nil? || value.start_with?("--")
+      arguments.slice!(index, 2)
+      value
+    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?
@@ -123,10 +151,12 @@ module OmarchyUI
       unless precompiled
         config.write_manifest(destination) if config&.plugin?
         bundle_ruby_entrypoint(source, destination, entrypoint:)
-        Runtime.install_package(destination, compiled: !config.nil?)
+        Runtime.install_package(destination, compiled: true)
       end
+      prune_bundled_ruby_sources(destination, entrypoint:)
       plugin = config ? config.plugin? : File.file?(File.join(destination, "manifest.json"))
       if plugin
+        PluginPackage.validate!(destination)
         raise ArgumentError, "bundled plugin validation failed" unless system("omarchy", "plugin", "validate", destination)
         @out.puts("Bundled plugin in #{destination}")
         return 0
@@ -161,23 +191,56 @@ module OmarchyUI
     end
 
     def application_entries(source, config: ProjectConfig.load(source))
-      generated = Runtime::GENERATED_ENTRIES + Runtime::AUDIT_FILES + %w[run Commons Ui]
+      generated = Runtime::GENERATED_ENTRIES + %w[run Commons Ui]
       generated.concat([ProjectConfig::FILE_NAME, "manifest.json"]) if config
-      Dir.children(source).reject { |entry| %w[.git dist].include?(entry) || generated.include?(entry) }
+      Dir.children(source).reject do |entry|
+        (PluginPackage::DEVELOPMENT_ENTRIES + PluginPackage::SOURCE_CONTROL_ENTRIES).include?(entry) ||
+          generated.include?(entry)
+      end
     end
 
     def package_entries(source)
-      Dir.children(source).reject { |entry| %w[.git dist].include?(entry) }
+      excluded = PluginPackage::DEVELOPMENT_ENTRIES + PluginPackage::SOURCE_CONTROL_ENTRIES +
+        Runtime::LEGACY_METADATA_FILES
+      Dir.children(source).reject { |entry| excluded.include?(entry) }
     end
 
     def compiled_package?(source)
-      report = File.join(source, QmlCompiler::REPORT)
-      return false unless File.file?(report)
+      compiled_root = File.join(source, QmlCompiler::COMPILED_ROOT, "Bundles")
+      shims = QmlCompiler::ENTRY_TYPES.keys.any? { |entry| File.file?(File.join(source, entry)) }
+      return false unless File.directory?(compiled_root) && shims
 
       QmlCompiler.verify!(source)
       true
     end
 
+    def publish(arguments)
+      repository = extract_option!(arguments, "--repo")
+      category = extract_option!(arguments, "--category")
+      tags = extract_option!(arguments, "--tags").to_s.split(",")
+      create = !arguments.delete("--create").nil?
+      submit = !arguments.delete("--submit").nil?
+      source = File.expand_path(arguments.shift || Dir.pwd)
+      raise ArgumentError, "publish accepts one directory and publish options" unless arguments.empty?
+      config = ProjectConfig.load(source)
+      raise ArgumentError, "publish requires an Omarchy UI plugin project" unless config&.plugin?
+
+      with_staged_project(source) do |staging|
+        raise ArgumentError, "staged plugin validation failed" unless system("omarchy", "plugin", "validate", staging)
+        PluginPublisher.publish!(
+          package: staging,
+          source:,
+          repository:,
+          category:,
+          tags:,
+          create:,
+          submit:,
+          out: @out
+        )
+      end
+      0
+    end
+
     def push(arguments)
       enable = !arguments.delete("--no-enable")
       restart = !arguments.delete("--no-restart")
@@ -239,9 +302,11 @@ module OmarchyUI
         entrypoint = config&.entrypoint || "main.rb"
         if File.file?(File.join(staging, entrypoint))
           bundle_ruby_entrypoint(source, staging, entrypoint:)
-          Runtime.install_package(staging, compiled: !config.nil?)
+          Runtime.install_package(staging, compiled: true)
         end
       end
+      prune_bundled_ruby_sources(staging, entrypoint: "main.rb") if File.file?(File.join(staging, "manifest.json"))
+      PluginPackage.validate!(staging) if File.file?(File.join(staging, "manifest.json"))
       staging
     rescue StandardError
       FileUtils.remove_entry(staging) if staging && File.exist?(staging)
@@ -255,6 +320,17 @@ module OmarchyUI
       File.write(destination_entrypoint, SourceBundle.new(source_entrypoint, root: source).call)
     end
 
+    def prune_bundled_ruby_sources(destination, entrypoint: "main.rb")
+      kept = File.expand_path(entrypoint, destination)
+      Dir.glob(File.join(destination, "**", "*.rb"), File::FNM_DOTMATCH).each do |path|
+        FileUtils.rm_f(path) unless File.expand_path(path) == kept
+      end
+      directories = Dir.glob(File.join(destination, "**", "*"), File::FNM_DOTMATCH)
+        .select { |path| File.directory?(path) && !File.symlink?(path) }
+        .sort_by { |path| -path.count(File::SEPARATOR) }
+      directories.each { |path| Dir.rmdir(path) if Dir.empty?(path) }
+    end
+
     def activate_plugin(plugin_id)
       return if system("omarchy", "plugin", "enable", plugin_id)
       system("omarchy-shell", "shell", "rescanPlugins")

data/lib/omarchy_ui/generator.rb

@@ -5,12 +5,17 @@ require "fileutils"
 module OmarchyUI
   class Generator
     PROJECT_KINDS = %i[application plugin].freeze
+    GITHUB_USER = /\A(?!-)[A-Za-z0-9-]{1,39}(?<!-)\z/
 
-    def initialize(path:, name: nil, kind: :application, plugin_id: nil, author: nil)
+    def initialize(path:, name: nil, kind: :application, plugin_id: nil, author: nil, github_user: nil)
       @path = File.expand_path(path)
       @name = name || File.basename(@path).split(/[-_]/).map(&:capitalize).join(" ")
       @kind = kind.to_sym
-      @plugin_id = plugin_id || "local.#{project_slug}"
+      @github_user = github_user.to_s.strip
+      if plugin? && !GITHUB_USER.match?(@github_user)
+        raise ArgumentError, "plugin generation needs a valid GitHub username"
+      end
+      @plugin_id = plugin_id || "io.github.#{@github_user.downcase}.#{project_slug}"
       @author = author.to_s.strip.empty? ? "Omarchy UI Developer" : author.to_s.strip
       raise ArgumentError, "unsupported project kind: #{@kind}" unless PROJECT_KINDS.include?(@kind)
     end
@@ -124,6 +129,9 @@ module OmarchyUI
 
         A pure Ruby desktop application built with Zui and the Omarchy UI host.
 
+        The interface and behavior are authored entirely in Ruby. Omarchy UI generates QML only
+        as a temporary build input, compiles it, and ships no handwritten QML source.
+
         ## Run
 
         ```bash
@@ -140,7 +148,9 @@ module OmarchyUI
         ```
 
         Omarchy UI tree-shakes and compiles the UI, then generates the complete self-contained
-        application package required by Omarchy.
+        application package required by Omarchy. The package contains the bundled Ruby program,
+        native runtime, compiled Qt module, and one generated `App.qml` loader shim—no build reports
+        or generated QML source tree.
       MARKDOWN
     end
 
@@ -150,6 +160,26 @@ module OmarchyUI
 
         A pure Ruby Omarchy plugin built with Omarchy UI and Zui.
 
+        The interface and behavior are authored entirely in Ruby. Omarchy UI generates QML only
+        as a temporary build input, compiles it, and ships no handwritten QML source.
+
+        ## Install
+
+        ```bash
+        omarchy plugin add https://github.com/#{@github_user}/#{project_slug}.git --enable
+        ```
+
+        ## Remove
+
+        ```bash
+        omarchy plugin remove #{@plugin_id}
+        ```
+
+        ## Dependencies
+
+        - Omarchy Quattro on x86-64 Linux
+        - No additional runtime dependency in the generated starter
+
         ## Validate
 
         ```bash
@@ -171,6 +201,9 @@ module OmarchyUI
         Write the plugin interface and behavior in Ruby under `main.rb` and `components/`.
         Public plugin identity and release metadata live in `config.rb`. Omarchy UI tree-shakes and
         compiles the UI, then generates and validates the complete Omarchy-compatible plugin package.
+        The package contains the bundled Ruby program, native runtime, compiled Qt module, manifest,
+        and only the generated loader shims named by that manifest—no build reports, audit folder,
+        tests, or generated QML source tree.
       MARKDOWN
     end
 

data/lib/omarchy_ui/plugin_package.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OmarchyUI
+  class PluginPackage
+    DEVELOPMENT_ENTRIES = %w[
+      .github .gitattributes .gitignore audit build config.rb dist docs qml-source spec test tests vendor
+    ].freeze
+    SOURCE_CONTROL_ENTRIES = %w[.git].freeze
+    README_PATTERN = /\Areadme(?:\.[^.]+)?\z/i
+    LICENSE_PATTERN = /\A(?:license|copying)(?:\.[^.]+)?\z/i
+    REQUIRED_MANIFEST_STRINGS = %w[id name version author license description].freeze
+
+    def self.validate!(path)
+      new(path).validate!
+    end
+
+    def initialize(path)
+      @path = File.expand_path(path)
+    end
+
+    def validate!
+      validate_root_files!
+      manifest = read_manifest
+      validate_manifest!(manifest)
+      validate_readme!(manifest)
+      validate_runtime!
+      validate_ruby_surface!
+      validate_qml_surface!(manifest)
+      QmlCompiler.verify!(@path)
+      manifest
+    end
+
+    private
+
+    def validate_root_files!
+      entries = Dir.children(@path)
+      forbidden = entries & (DEVELOPMENT_ENTRIES + Runtime::LEGACY_METADATA_FILES)
+      unless forbidden.empty?
+        raise ArgumentError, "plugin package contains development-only entries: #{forbidden.sort.join(', ')}"
+      end
+
+      manifests = Dir.glob(File.join(@path, "**", "manifest.json"), File::FNM_DOTMATCH)
+        .select { |path| File.file?(path) }
+      unless manifests == [File.join(@path, "manifest.json")]
+        raise ArgumentError, "plugin package must contain exactly one root manifest.json"
+      end
+
+      readmes = entries.grep(README_PATTERN).select { |entry| File.file?(File.join(@path, entry)) }
+      raise ArgumentError, "plugin package needs one root README" unless readmes.length == 1
+
+      licenses = entries.grep(LICENSE_PATTERN).select { |entry| File.file?(File.join(@path, entry)) }
+      raise ArgumentError, "plugin package needs one root license file" unless licenses.length == 1
+
+      symlinks = Dir.glob(File.join(@path, "**", "*"), File::FNM_DOTMATCH)
+        .select { |path| File.symlink?(path) }
+      unless symlinks.empty?
+        raise ArgumentError, "plugin package may not contain symbolic links"
+      end
+    end
+
+    def read_manifest
+      JSON.parse(File.read(File.join(@path, "manifest.json")))
+    rescue JSON::ParserError => error
+      raise ArgumentError, "invalid plugin manifest: #{error.message}"
+    end
+
+    def validate_manifest!(manifest)
+      unless manifest.is_a?(Hash) && manifest["schemaVersion"] == 1
+        raise ArgumentError, "plugin manifest must use schemaVersion 1"
+      end
+      REQUIRED_MANIFEST_STRINGS.each do |field|
+        value = manifest[field]
+        unless value.is_a?(String) && !value.strip.empty?
+          raise ArgumentError, "plugin manifest needs a non-empty #{field}"
+        end
+      end
+      plugin_id = manifest.fetch("id")
+      raise ArgumentError, "invalid plugin id" unless VALID_ID.match?(plugin_id)
+      if plugin_id.start_with?("omarchy.")
+        raise ArgumentError, "plugin id uses the reserved omarchy.* namespace"
+      end
+
+      entry_points = manifest["entryPoints"]
+      unless entry_points.is_a?(Hash) && !entry_points.empty?
+        raise ArgumentError, "plugin manifest needs entryPoints"
+      end
+      files = entry_points.values
+      unless files.all? { |file| file.is_a?(String) } && files.uniq.length == files.length
+        raise ArgumentError, "plugin manifest entryPoints must be unique file names"
+      end
+      unsupported = files - QmlCompiler::ENTRY_TYPES.keys
+      unless unsupported.empty?
+        raise ArgumentError, "unsupported plugin entryPoints: #{unsupported.join(', ')}"
+      end
+    end
+
+    def validate_readme!(manifest)
+      name = Dir.children(@path).find { |entry| README_PATTERN.match?(entry) }
+      readme = File.read(File.join(@path, name))
+      raise ArgumentError, "plugin README needs installation instructions" unless readme.match?(/install/i)
+      unless readme.match?(/(?:remove|uninstall)/i)
+        raise ArgumentError, "plugin README needs removal instructions"
+      end
+      unless readme.include?("omarchy plugin add")
+        raise ArgumentError, "plugin README needs an omarchy plugin add command"
+      end
+      unless readme.include?("omarchy plugin remove #{manifest.fetch('id')}")
+        raise ArgumentError, "plugin README removal command must use the manifest id"
+      end
+    end
+
+    def validate_runtime!
+      runtime = File.join(@path, "omarchy-ui-runtime")
+      unless File.file?(runtime) && File.executable?(runtime) && !File.symlink?(runtime)
+        raise ArgumentError, "plugin package needs an executable omarchy-ui-runtime"
+      end
+    end
+
+    def validate_ruby_surface!
+      entrypoint = File.join(@path, "main.rb")
+      unless File.file?(entrypoint) && !File.symlink?(entrypoint)
+        raise ArgumentError, "plugin package needs one bundled main.rb"
+      end
+
+      ruby_files = Dir.glob(File.join(@path, "**", "*.rb"), File::FNM_DOTMATCH)
+        .select { |path| File.file?(path) }
+        .map { |path| path.delete_prefix("#{@path}/") }
+        .sort
+      unless ruby_files == ["main.rb"]
+        raise ArgumentError, "plugin package may contain only the bundled main.rb Ruby program"
+      end
+    end
+
+    def validate_qml_surface!(manifest)
+      expected = manifest.fetch("entryPoints").values.sort
+      qml_files = Dir.glob(File.join(@path, "**", "*.qml"), File::FNM_DOTMATCH)
+        .select { |path| File.file?(path) }
+        .map { |path| path.delete_prefix("#{@path}/") }
+        .sort
+      unless qml_files == expected
+        raise ArgumentError, "plugin package may contain only manifest-declared generated QML shims"
+      end
+    end
+  end
+end

data/lib/omarchy_ui/plugin_publisher.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "tmpdir"
+
+module OmarchyUI
+  class PluginPublisher
+    MARKETPLACE_REPOSITORY = "omacom/omarchy-plugin-marketplace"
+    CATEGORIES = [
+      "Appearance", "Desktop", "Developer Tools", "Hardware", "Kids", "Productivity", "System", "Widgets", "Other"
+    ].freeze
+    TAGS = %w[
+      ai bar education games hyprland kids launcher media power-management quickshell security system workspaces
+    ].freeze
+    REPOSITORY = /\A[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\z/
+
+    def self.publish!(**arguments)
+      new(**arguments).publish!
+    end
+
+    def initialize(package:, source:, repository:, category:, tags:, create: false, submit: false,
+                   marketplace_repository: ENV.fetch("OMARCHY_UI_MARKETPLACE_REPOSITORY", MARKETPLACE_REPOSITORY),
+                   out: $stdout)
+      @package = File.expand_path(package)
+      @source = File.expand_path(source)
+      @repository = repository.to_s.strip
+      @category = category.to_s.strip
+      @tags = Array(tags).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+      @create = create
+      @submit = submit
+      @marketplace_repository = marketplace_repository.to_s.strip
+      @out = out
+    end
+
+    def publish!
+      validate_options!
+      manifest = PluginPackage.validate!(@package)
+      validate_install_url!
+      ensure_distinct_repository!
+      ensure_gh_authenticated!
+      ensure_distribution_repository!(manifest)
+      commit = publish_package!(manifest)
+      title = "[Plugin]: #{manifest.fetch('name')}"
+      body = submission_body(commit:)
+      show_submission(title, body)
+      if @submit
+        issue_url = submit_to_marketplace!(title, body)
+        @out.puts("Marketplace submission: #{issue_url}")
+      else
+        @out.puts("Review the submission above, then rerun with --submit to create or refresh it.")
+      end
+      @out.puts("Published #{@repository} at #{commit}")
+      commit
+    end
+
+    private
+
+    def validate_options!
+      raise ArgumentError, "publish requires --repo OWNER/REPOSITORY" unless REPOSITORY.match?(@repository)
+      raise ArgumentError, "invalid marketplace repository" unless REPOSITORY.match?(@marketplace_repository)
+      unless CATEGORIES.include?(@category)
+        raise ArgumentError, "publish category must be one of: #{CATEGORIES.join(', ')}"
+      end
+      unless (1..3).cover?(@tags.length) && (@tags - TAGS).empty?
+        raise ArgumentError, "publish needs one to three allowed tags: #{TAGS.join(', ')}"
+      end
+    end
+
+    def ensure_distinct_repository!
+      output, _error, status = capture("git", "-C", @source, "remote", "get-url", "origin")
+      return unless status.success?
+
+      source_repository = github_repository(output.strip)
+      if source_repository&.casecmp?(@repository)
+        raise ArgumentError,
+          "publish target must be a separate distribution repository; refusing to replace the source repository"
+      end
+    end
+
+    def validate_install_url!
+      readme_name = Dir.children(@package).find { |entry| PluginPackage::README_PATTERN.match?(entry) }
+      readme = File.read(File.join(@package, readme_name))
+      repository_url = "https://github.com/#{@repository}"
+      return if readme.downcase.include?(repository_url.downcase)
+
+      raise ArgumentError,
+        "plugin README install command must use the distribution repository #{repository_url}"
+    end
+
+    def ensure_gh_authenticated!
+      _output, error, status = capture("gh", "auth", "status")
+      return if status.success?
+
+      detail = error.strip.lines.last.to_s.strip
+      raise ArgumentError, "GitHub CLI authentication is required#{detail.empty? ? '' : ": #{detail}"}"
+    rescue Errno::ENOENT
+      raise ArgumentError, "publish requires the GitHub CLI (gh)"
+    end
+
+    def ensure_distribution_repository!(manifest)
+      output, error, status = capture(
+        "gh", "repo", "view", @repository,
+        "--json", "nameWithOwner,visibility", "--jq", "[.nameWithOwner,.visibility] | @tsv"
+      )
+      unless status.success?
+        unless @create
+          raise ArgumentError,
+            "distribution repository #{@repository} was not found; create it first or rerun with --create"
+        end
+        run!(
+          "gh", "repo", "create", @repository, "--public",
+          "--description", "#{manifest.fetch('name')} — an Omarchy plugin built entirely in Ruby"
+        )
+        output, error, status = capture(
+          "gh", "repo", "view", @repository,
+          "--json", "nameWithOwner,visibility", "--jq", "[.nameWithOwner,.visibility] | @tsv"
+        )
+      end
+      unless status.success?
+        raise ArgumentError, "could not inspect distribution repository: #{error.strip}"
+      end
+
+      _name, visibility = output.strip.split("\t", 2)
+      raise ArgumentError, "distribution repository must be public" unless visibility == "PUBLIC"
+    end
+
+    def publish_package!(manifest)
+      Dir.mktmpdir("omarchy-ui-publish-") do |temporary|
+        checkout = File.join(temporary, "repository")
+        run!("gh", "repo", "clone", @repository, checkout, "--", "--quiet")
+        guard_existing_package!(checkout, manifest)
+        replace_checkout!(checkout)
+        run!("git", "-C", checkout, "add", "-A")
+        _output, _error, clean = capture("git", "-C", checkout, "diff", "--cached", "--quiet")
+        unless clean.success?
+          run!(
+            "git", "-C", checkout, "commit", "-m",
+            "Publish #{manifest.fetch('name')} #{manifest.fetch('version')}"
+          )
+          run!("git", "-C", checkout, "push", "origin", "HEAD")
+        end
+        output, _error, _status = capture("git", "-C", checkout, "rev-parse", "HEAD")
+        output.strip
+      end
+    end
+
+    def guard_existing_package!(checkout, manifest)
+      entries = Dir.children(checkout) - [".git"]
+      return if entries.empty?
+
+      existing_manifest = File.join(checkout, "manifest.json")
+      unless File.file?(existing_manifest)
+        raise ArgumentError, "distribution repository is not empty and has no root manifest.json"
+      end
+      existing_id = JSON.parse(File.read(existing_manifest)).fetch("id")
+      return if existing_id == manifest.fetch("id")
+
+      raise ArgumentError,
+        "distribution repository contains plugin #{existing_id.inspect}, not #{manifest.fetch('id').inspect}"
+    rescue JSON::ParserError, KeyError => error
+      raise ArgumentError, "distribution repository has an invalid manifest: #{error.message}"
+    end
+
+    def replace_checkout!(checkout)
+      (Dir.children(checkout) - [".git"]).each do |entry|
+        FileUtils.remove_entry(File.join(checkout, entry))
+      end
+      Dir.children(@package).each do |entry|
+        FileUtils.cp_r(File.join(@package, entry), File.join(checkout, entry), preserve: true)
+      end
+    end
+
+    def submission_body(commit:)
+      <<~MARKDOWN
+        ### Repository URL
+
+        https://github.com/#{@repository}
+
+        ### Category
+
+        #{@category}
+
+        ### Tags
+
+        #{@tags.join(', ')}
+
+        ### Suggest a missing tag
+
+        _No response_
+
+        ### Maintainer notes
+
+        Built and published by Omarchy UI as a thin Ruby-authored package. Current review target: `#{commit}`.
+
+        ### Submission checklist
+
+        - [x] The repository is public and contains installation and removal instructions.
+        - [x] I have documented the plugin license and any external dependencies.
+        - [x] I confirm that I own or have permission to submit this plugin and its preview assets.
+        - [x] The plugin does not overwrite user configuration without explicit consent.
+        - [x] I understand that approval is for listing and is not a security review.
+      MARKDOWN
+    end
+
+    def show_submission(title, body)
+      @out.puts("Marketplace issue preview (#{@marketplace_repository}):")
+      @out.puts(title)
+      @out.puts(body)
+    end
+
+    def submit_to_marketplace!(title, body)
+      output, error, status = capture(
+        "gh", "issue", "list", "--repo", @marketplace_repository, "--state", "all", "--limit", "1000",
+        "--json", "number,body,state,url"
+      )
+      raise ArgumentError, "could not inspect marketplace submissions: #{error.strip}" unless status.success?
+
+      repository_url = "https://github.com/#{@repository}"
+      matching = JSON.parse(output).select { |issue| issue.fetch("body", "").include?(repository_url) }
+      open_issue = matching.find { |issue| issue.fetch("state") == "OPEN" }
+      if open_issue
+        run!(
+          "gh", "issue", "edit", open_issue.fetch("number").to_s,
+          "--repo", @marketplace_repository, "--title", title, "--body", body
+        )
+        return open_issue.fetch("url")
+      end
+      if matching.any?
+        raise ArgumentError,
+          "this repository already has a closed marketplace submission; use the marketplace verification/update form"
+      end
+
+      created, create_error, create_status = capture(
+        "gh", "issue", "create", "--repo", @marketplace_repository, "--title", title, "--body", body
+      )
+      raise ArgumentError, "marketplace submission failed: #{create_error.strip}" unless create_status.success?
+
+      created.lines.map(&:strip).find { |line| line.start_with?("https://") } || created.strip
+    rescue JSON::ParserError, KeyError => error
+      raise ArgumentError, "invalid marketplace response: #{error.message}"
+    end
+
+    def github_repository(url)
+      value = url.to_s.strip.sub(/\.git\z/, "")
+      match = value.match(%r{(?:github\.com[/:])([^/]+/[^/]+)\z}i)
+      match && match[1]
+    end
+
+    def capture(*command)
+      Open3.capture3(*command)
+    end
+
+    def run!(*command)
+      output, error, status = capture(*command)
+      return output if status.success?
+
+      detail = [output, error].join("\n").strip
+      raise ArgumentError, "command failed: #{command.first}#{detail.empty? ? '' : ": #{detail}"}"
+    end
+  end
+end

data/lib/omarchy_ui/project_config.rb

@@ -191,6 +191,7 @@ module OmarchyUI
     def validate_plugin!
       %i[id author license description].each { |key| required_string!(key) }
       raise ArgumentError, "invalid plugin id" unless VALID_ID.match?(@data[:id])
+      raise ArgumentError, "plugin entrypoint must be main.rb" unless entrypoint == "main.rb"
 
       widget = @data[:bar_widget]
       raise ArgumentError, "plugin project config is missing bar widget metadata" unless widget.is_a?(Hash)

data/lib/omarchy_ui/qml_compiler.rb

@@ -4,7 +4,6 @@ require "digest"
 require "fileutils"
 require "json"
 require "open3"
-require "pathname"
 require "tmpdir"
 
 module OmarchyUI
@@ -22,16 +21,17 @@ module OmarchyUI
     CHECKSUM = "omarchy-ui-qml-bundle.sha256"
     PROVENANCE = "QML_PROVENANCE.md"
 
-    def self.compile!(path)
-      new(path).compile!
+    def self.compile!(path, entry_files: ENTRY_TYPES.keys)
+      new(path, entry_files:).compile!
     end
 
     def self.verify!(path)
       new(path).verify!
     end
 
-    def initialize(path)
+    def initialize(path, entry_files: nil)
       @path = File.expand_path(path)
+      @entry_types = entry_files ? select_entry_types(entry_files) : nil
     end
 
     def compile!
@@ -61,66 +61,107 @@ module OmarchyUI
         ))
         configure!(tools.fetch(:qt_cmake), source, build)
         build!(tools.fetch(:cmake), build)
-        deploy!(
-          build:,
-          module_path:,
-          target:,
-          uri:,
-          fingerprint:,
-          qml_files:,
-          resources:,
-          source:,
-          expected_qt_version: qt_version
-        )
+        deploy!(build:, module_path:, target:, uri:, expected_qt_version: qt_version)
       end
     end
 
     def verify!
-      report_path = File.join(@path, REPORT)
-      raise ArgumentError, "compiled QML report is missing: #{report_path}" unless File.file?(report_path)
-
-      report = JSON.parse(File.read(report_path))
-      unless report["format"] == "qt-aot-qml-module" && report["format_version"] == FORMAT_VERSION
-        raise ArgumentError, "unsupported compiled QML package format"
+      entry_types = packaged_entry_types
+      module_path, module_uri = packaged_module
+      entry_types.each do |entry, type|
+        shim = File.read(File.join(@path, entry)).strip
+        expected = entry_shim(module_path, type, uri: module_uri).strip
+        raise ArgumentError, "invalid compiled QML entry shim: #{entry}" unless shim == expected
       end
-      ENTRY_TYPES.each_key do |entry|
-        raise ArgumentError, "compiled QML entry shim is missing: #{entry}" unless File.file?(File.join(@path, entry))
+
+      segment = File.basename(module_path)
+      target = "omarchy_ui_bundle_#{segment.downcase}"
+      artifact_names = ["lib#{target}.so", "lib#{target}plugin.so"]
+      module_directory = File.join(@path, module_path)
+      expected_module_entries = (artifact_names + ["qmldir"]).sort
+      unless Dir.children(module_directory).sort == expected_module_entries
+        raise ArgumentError, "compiled QML module contains unexpected files"
       end
-      module_path = safe_relative_path(report.fetch("module_path"))
-      raise ArgumentError, "compiled QML qmldir is missing" unless File.file?(File.join(@path, module_path, "qmldir"))
-
-      artifacts = report.fetch("artifacts")
-      raise ArgumentError, "compiled QML package must contain two libraries" unless artifacts.length == 2
-      artifacts.each do |artifact|
-        relative = safe_relative_path(artifact.fetch("path"))
-        unless relative.start_with?("#{module_path}/") && relative.end_with?(".so")
-          raise ArgumentError, "compiled QML artifact is outside its module: #{relative}"
-        end
+      artifacts = artifact_names.map do |name|
+        relative = File.join(module_path, name)
         absolute = File.join(@path, relative)
-        raise ArgumentError, "compiled QML artifact is missing: #{relative}" unless File.file?(absolute)
-        unless File.size(absolute) == artifact.fetch("bytes") &&
-            Digest::SHA256.file(absolute).hexdigest == artifact.fetch("sha256")
-          raise ArgumentError, "compiled QML artifact checksum mismatch: #{relative}"
-        end
+        {
+          "path" => relative,
+          "sha256" => Digest::SHA256.file(absolute).hexdigest,
+          "bytes" => File.size(absolute)
+        }
       end
-      report
-    rescue JSON::ParserError, KeyError, TypeError => error
-      raise ArgumentError, "invalid compiled QML report: #{error.message}"
+      {
+        "format" => "qt-aot-qml-module",
+        "format_version" => FORMAT_VERSION,
+        "module_uri" => module_uri,
+        "module_path" => module_path,
+        "entry_shims" => entry_types.keys,
+        "artifacts" => artifacts
+      }
     end
 
     private
 
-    def safe_relative_path(path)
-      value = path.to_s
-      clean = File.expand_path(value, @path)
-      unless !value.empty? && !Pathname.new(value).absolute? && clean.start_with?("#{@path}/")
-        raise ArgumentError, "unsafe compiled QML path: #{value.inspect}"
+    def select_entry_types(entry_files)
+      entries = Array(entry_files).map(&:to_s).uniq
+      unknown = entries - ENTRY_TYPES.keys
+      raise ArgumentError, "unsupported compiled QML entries: #{unknown.join(', ')}" unless unknown.empty?
+      raise ArgumentError, "compiled QML package needs at least one entry point" if entries.empty?
+
+      entries.to_h { |entry| [entry, ENTRY_TYPES.fetch(entry)] }
+    end
+
+    def packaged_entry_types
+      selected = if File.file?(File.join(@path, "manifest.json"))
+        manifest = JSON.parse(File.read(File.join(@path, "manifest.json")))
+        select_entry_types(manifest.fetch("entryPoints").values)
+      else
+        select_entry_types(ENTRY_TYPES.keys.select { |entry| File.file?(File.join(@path, entry)) })
+      end
+      actual = ENTRY_TYPES.keys.select { |entry| File.file?(File.join(@path, entry)) }
+      unless actual.sort == selected.keys.sort
+        raise ArgumentError, "compiled QML package contains unexpected entry shims"
       end
-      clean.delete_prefix("#{@path}/")
+      selected
+    rescue JSON::ParserError, KeyError, TypeError => error
+      raise ArgumentError, "invalid plugin manifest: #{error.message}"
+    end
+
+    def packaged_module
+      compiled_root = File.join(@path, COMPILED_ROOT)
+      unless File.directory?(compiled_root) && !File.symlink?(compiled_root) &&
+          Dir.children(compiled_root) == ["Bundles"]
+        raise ArgumentError, "compiled QML root must contain only the Bundles directory"
+      end
+      bundles = File.join(compiled_root, "Bundles")
+      directories = if File.directory?(bundles) && !File.symlink?(bundles)
+        Dir.children(bundles).sort.filter_map do |entry|
+          path = File.join(bundles, entry)
+          path if File.directory?(path) && !File.symlink?(path)
+        end
+      else
+        []
+      end
+      raise ArgumentError, "compiled QML package must contain exactly one module" unless directories.length == 1
+
+      directory = directories.first
+      module_path = directory.delete_prefix("#{@path}/")
+      qmldir = File.join(directory, "qmldir")
+      unless File.file?(qmldir) && !File.symlink?(qmldir)
+        raise ArgumentError, "compiled QML qmldir is missing"
+      end
+      module_uri = File.read(qmldir)[/^module\s+(\S+)\s*$/, 1]
+      raise ArgumentError, "compiled QML module declaration is missing" unless module_uri
+      unless File.join(*module_uri.split(".")) == module_path
+        raise ArgumentError, "compiled QML module path does not match its URI"
+      end
+
+      [module_path, module_uri]
     end
 
     def validate_sources!
-      missing = ENTRY_TYPES.keys.reject { |entry| File.file?(File.join(@path, entry)) }
+      missing = @entry_types.keys.reject { |entry| File.file?(File.join(@path, entry)) }
       missing << "ControlNode.qml" unless File.file?(File.join(@path, "ControlNode.qml"))
       return if missing.empty?
 
@@ -163,7 +204,7 @@ module OmarchyUI
 
     def stage_sources(destination)
       FileUtils.mkdir_p(destination)
-      SOURCE_ENTRIES.each do |entry|
+      (@entry_types.keys + SOURCE_ENTRIES.drop(ENTRY_TYPES.length)).each do |entry|
         source = File.join(@path, entry)
         next unless File.exist?(source)
 
@@ -281,8 +322,7 @@ module OmarchyUI
       raise ArgumentError, "#{label} failed#{detail.empty? ? '' : ":\n#{detail}"}"
     end
 
-    def deploy!(build:, module_path:, target:, uri:, fingerprint:, qml_files:, resources:, source:,
-      expected_qt_version:)
+    def deploy!(build:, module_path:, target:, uri:, expected_qt_version:)
       built_module = File.join(build, module_path)
       artifact_names = ["lib#{target}.so", "lib#{target}plugin.so", "qmldir"]
       missing = artifact_names.reject { |name| File.file?(File.join(built_module, name)) }
@@ -304,38 +344,10 @@ module OmarchyUI
       File.write(qmldir, File.read(qmldir).rstrip + "\n")
 
       SOURCE_ENTRIES.each { |entry| remove_generated(File.join(@path, entry)) }
-      ENTRY_TYPES.each do |entry, type|
+      @entry_types.each do |entry, type|
         File.write(File.join(@path, entry), entry_shim(module_path, type, uri:))
       end
-
-      artifact_paths = artifact_names.filter_map do |name|
-        next if name == "qmldir"
-
-        relative = File.join(module_path, name)
-        absolute = File.join(@path, relative)
-        {
-          "path" => relative,
-          "sha256" => Digest::SHA256.file(absolute).hexdigest,
-          "bytes" => File.size(absolute)
-        }
-      end
-      report = {
-        "format" => "qt-aot-qml-module",
-        "format_version" => FORMAT_VERSION,
-        "qt_version" => qt_version,
-        "module_uri" => uri,
-        "module_path" => module_path,
-        "source_fingerprint" => fingerprint,
-        "source_files" => qml_files.length,
-        "source_bytes" => (qml_files + resources).sum { |file| File.size(File.join(source, file)) },
-        "entry_shims" => ENTRY_TYPES.keys,
-        "artifacts" => artifact_paths
-      }
-      File.write(File.join(@path, REPORT), JSON.pretty_generate(report) + "\n")
-      checksums = artifact_paths.map { |artifact| "#{artifact.fetch('sha256')}  #{artifact.fetch('path')}" }
-      File.write(File.join(@path, CHECKSUM), checksums.join("\n") + "\n")
-      File.write(File.join(@path, PROVENANCE), provenance(report))
-      report
+      verify!
     end
 
     def remove_generated(path)
@@ -352,35 +364,5 @@ module OmarchyUI
       QML
     end
 
-    def provenance(report)
-      artifacts = report.fetch("artifacts").map do |artifact|
-        "- `#{artifact.fetch('path')}` — `#{artifact.fetch('sha256')}`"
-      end.join("\n")
-      <<~MARKDOWN
-        # Compiled QML provenance
-
-        Omarchy UI generated this package's native Qt module from the tree-shaken Zui and
-        Omarchy host QML graph. Generated QML source contents were discarded after AOT compilation.
-
-        - Format: `#{report.fetch('format')}` version #{report.fetch('format_version')}
-        - Qt: `#{report.fetch('qt_version')}`
-        - Module: `#{report.fetch('module_uri')}`
-        - Source fingerprint: `#{report.fetch('source_fingerprint')}`
-
-        ## Artifacts
-
-        #{artifacts}
-
-        Verify the packaged libraries from the plugin directory:
-
-        ```bash
-        sha256sum --check #{CHECKSUM}
-        ```
-
-        `App.qml`, `Service.qml`, `Panel.qml`, and `BarWidget.qml` are the minimal loader shims
-        required by Omarchy's file-based entry-point contract. Application UI lives in the compiled
-        module recorded by `#{REPORT}`.
-      MARKDOWN
-    end
   end
 end

data/lib/omarchy_ui/runtime.rb

@@ -12,18 +12,18 @@ module OmarchyUI
     ADAPTER_FILES = %w[Service.qml Panel.qml BarWidget.qml App.qml].freeze
     ZUI_GENERATED_ENTRIES = %w[Desktop.qml ControlNode.qml Components Controls Theme Fonts].freeze
     TREE_SHAKE_REPORT = "zui-tree-shake.json"
+    SHELL_COMPONENT_ROOT = File.expand_path("../../qml", __dir__)
+    SHELL_COMPONENTS = %w[DesktopStage.qml Positioned.qml].freeze
     FILES = (ADAPTER_FILES + %w[ControlNode.qml]).freeze
-    AUDIT_FILES = %w[
+    LEGACY_METADATA_FILES = %W[
+      #{TREE_SHAKE_REPORT}
+      #{QmlCompiler::REPORT} #{QmlCompiler::CHECKSUM} #{QmlCompiler::PROVENANCE}
       omarchy-ui-runtime.sha256 runtime-provenance.json RUNTIME_PROVENANCE.md
     ].freeze
     GENERATED_ENTRIES = (ADAPTER_FILES + ZUI_GENERATED_ENTRIES + [
-      TREE_SHAKE_REPORT,
       QmlCompiler::COMPILED_ROOT,
-      QmlCompiler::REPORT,
-      QmlCompiler::CHECKSUM,
-      QmlCompiler::PROVENANCE,
       "omarchy-ui-runtime"
-    ]).freeze
+    ] + LEGACY_METADATA_FILES).freeze
 
     def executable
       override = ENV["OMARCHY_UI_RUNTIME"]
@@ -51,29 +51,17 @@ module OmarchyUI
         generated = File.join(path, entry)
         File.directory?(generated) ? FileUtils.remove_entry(generated) : FileUtils.rm_f(generated)
       end
-      report = install_tree_shaken_zui(path, project:)
+      install_tree_shaken_zui(path, project:)
       ADAPTER_FILES.each do |file|
         FileUtils.cp(File.join(framework_root, file), File.join(path, file))
       end
-      File.write(File.join(path, TREE_SHAKE_REPORT), JSON.pretty_generate({
-        "zui_version" => Zui::VERSION,
-        "components" => report.components.map(&:to_s),
-        "before_bytes" => report.before_bytes,
-        "after_bytes" => report.after_bytes,
-        "saved_bytes" => report.saved_bytes,
-        "warnings" => report.warnings
-      }) + "\n")
 
       if File.file?(BUNDLED)
         destination = File.join(path, "omarchy-ui-runtime")
         FileUtils.cp(BUNDLED, destination)
         FileUtils.chmod(0o755, destination)
       end
-      AUDIT_FILES.each do |file|
-        source = File.join(framework_root, "vendor", "runtime", "x86_64-linux", file)
-        FileUtils.cp(source, File.join(path, file)) if File.file?(source)
-      end
-      QmlCompiler.compile!(path) if compiled
+      QmlCompiler.compile!(path, entry_files: package_entry_files(path)) if compiled
       path
     end
 
@@ -88,11 +76,51 @@ module OmarchyUI
         FileUtils.mkdir_p(native)
         Zui::Runtime.install_qml(qml)
         report = Zui::TreeShaker.new(project:, framework: qml, native:).shake!
+        install_shell_components(qml)
         FileUtils.rm_f([File.join(qml, "Desktop.qml"), File.join(qml, "Service.qml")])
         entries = Dir.children(qml).map { |entry| File.join(qml, entry) }
         FileUtils.cp_r(entries, destination) unless entries.empty?
         return report
       end
     end
+
+    def package_entry_files(path)
+      manifest_path = File.join(path, "manifest.json")
+      return ["App.qml"] unless File.file?(manifest_path)
+
+      manifest = JSON.parse(File.read(manifest_path))
+      entries = manifest.fetch("entryPoints").values.map(&:to_s).uniq
+      unknown = entries - QmlCompiler::ENTRY_TYPES.keys
+      raise ArgumentError, "unsupported manifest QML entry points: #{unknown.join(', ')}" unless unknown.empty?
+      raise ArgumentError, "manifest has no QML entry points" if entries.empty?
+
+      entries
+    rescue JSON::ParserError, KeyError, TypeError => error
+      raise ArgumentError, "invalid plugin manifest: #{error.message}"
+    end
+
+    def install_shell_components(qml)
+      builtins = File.join(qml, "Components", "Builtins")
+      FileUtils.mkdir_p(builtins)
+      SHELL_COMPONENTS.each do |file|
+        FileUtils.cp(File.join(SHELL_COMPONENT_ROOT, file), File.join(builtins, file))
+      end
+
+      control_node = File.join(qml, "ControlNode.qml")
+      source = File.read(control_node)
+      source = source.sub(
+        'readonly property bool builtIn: ["text"',
+        'readonly property bool builtIn: ["desktop_stage", "positioned", "text"'
+      )
+      source = source.sub(
+        'readonly property bool structuralContainer: ["row"',
+        'readonly property bool structuralContainer: ["desktop_stage", "positioned", "row"'
+      )
+      source = source.sub(
+        'return bridge && bridge.projectDir ? bridge.projectDir + "/" + source : Qt.resolvedUrl(source)',
+        'return bridge && bridge.projectDir ? "file://" + bridge.projectDir + "/" + source : Qt.resolvedUrl(source)'
+      )
+      File.write(control_node, source)
+    end
   end
 end

data/lib/omarchy_ui.rb

@@ -11,7 +11,7 @@ rescue LoadError
 end
 
 module OmarchyUI
-  VERSION = "0.0.9"
+  VERSION = "0.0.10"
   ZUI_VERSION = Zui::VERSION
   FRAMEWORK_ROOT = File.expand_path("..", __dir__)
 
@@ -130,3 +130,5 @@ require_relative "omarchy_ui/project_config"
 require_relative "omarchy_ui/generator"
 require_relative "omarchy_ui/qml_compiler"
 require_relative "omarchy_ui/runtime"
+require_relative "omarchy_ui/plugin_package"
+require_relative "omarchy_ui/plugin_publisher"

data/qml/DesktopStage.qml

@@ -0,0 +1,88 @@
+import QtQuick
+import Quickshell
+import Quickshell.Wayland
+
+PanelWindow {
+  id: window
+
+  required property var renderer
+  readonly property real requestedX: Number(renderer.prop("stage_x", 48))
+  readonly property real requestedY: Number(renderer.prop("stage_y", 220))
+  property real sceneX: requestedX
+  property real sceneY: requestedY
+
+  function boundedX(value) {
+    return Math.max(0, Math.min(width - stage.width, Number(value)))
+  }
+
+  function boundedY(value) {
+    return Math.max(0, Math.min(height - stage.height, Number(value)))
+  }
+
+  function send(name, payload) {
+    if (renderer.subscribed(name))
+      renderer.bridge.sendEvent(renderer.surfaceName, renderer.controlId, name, payload || {})
+  }
+
+  onRequestedXChanged: if (!sceneDrag.active) sceneX = boundedX(requestedX)
+  onRequestedYChanged: if (!sceneDrag.active) sceneY = boundedY(requestedY)
+
+  visible: renderer.prop("pinned", false) === true
+  anchors { top: true; right: true; bottom: true; left: true }
+  color: "transparent"
+  exclusionMode: ExclusionMode.Ignore
+  WlrLayershell.namespace: renderer.bridge && renderer.bridge.manifest && renderer.bridge.manifest.id
+    ? String(renderer.bridge.manifest.id) + "-desktop"
+    : "omarchy-ui-desktop"
+  WlrLayershell.layer: WlrLayer.Overlay
+  WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
+
+  // The rest of the full-screen surface remains click-through.
+  mask: Region { item: stage }
+
+  Item {
+    id: stage
+    x: window.boundedX(window.sceneX)
+    y: window.boundedY(window.sceneY)
+    width: Math.max(1, Number(renderer.prop("stage_width", 420)))
+    height: Math.max(1, Number(renderer.prop("stage_height", 420)))
+
+    DragHandler {
+      id: sceneDrag
+      target: null
+      enabled: renderer.prop("draggable", true) !== false
+      dragThreshold: 3
+      property real originX: 0
+      property real originY: 0
+
+      onActiveChanged: {
+        if (active) {
+          originX = stage.x
+          originY = stage.y
+          window.send("drag_start", { target_x: stage.x, target_y: stage.y })
+        } else {
+          window.sceneX = stage.x
+          window.sceneY = stage.y
+          window.send("drag_end", { target_x: stage.x, target_y: stage.y })
+        }
+      }
+
+      onTranslationChanged: {
+        if (!active) return
+        window.sceneX = window.boundedX(originX + translation.x)
+        window.sceneY = window.boundedY(originY + translation.y)
+        window.send("drag", { target_x: stage.x, target_y: stage.y })
+      }
+    }
+
+    HoverHandler {
+      enabled: sceneDrag.enabled
+      cursorShape: sceneDrag.active ? Qt.ClosedHandCursor : Qt.OpenHandCursor
+    }
+
+    Repeater {
+      model: renderer.node && Array.isArray(renderer.node.children) ? renderer.node.children : []
+      delegate: renderer.childDelegateComponent
+    }
+  }
+}

data/qml/Positioned.qml

@@ -0,0 +1,18 @@
+import QtQuick
+
+Item {
+  id: root
+
+  required property var renderer
+
+  x: Number(renderer.prop("position_x", 0))
+  y: Number(renderer.prop("position_y", 0))
+  width: Math.max(1, Number(renderer.prop("item_width", 1)))
+  height: Math.max(1, Number(renderer.prop("item_height", 1)))
+  clip: renderer.prop("clip", false) === true
+
+  Repeater {
+    model: renderer.node && Array.isArray(renderer.node.children) ? renderer.node.children : []
+    delegate: renderer.childDelegateComponent
+  }
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omarchy-ui
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.10
 platform: x86_64-linux
 authors:
 - Adam Moussa Ali
@@ -39,9 +39,13 @@ files:
 - lib/omarchy_ui.rb
 - lib/omarchy_ui/cli.rb
 - lib/omarchy_ui/generator.rb
+- lib/omarchy_ui/plugin_package.rb
+- lib/omarchy_ui/plugin_publisher.rb
 - lib/omarchy_ui/project_config.rb
 - lib/omarchy_ui/qml_compiler.rb
 - lib/omarchy_ui/runtime.rb
+- qml/DesktopStage.qml
+- qml/Positioned.qml
 - vendor/runtime/x86_64-linux/RUNTIME_PROVENANCE.md
 - vendor/runtime/x86_64-linux/omarchy-ui-runtime
 - vendor/runtime/x86_64-linux/omarchy-ui-runtime.sha256