omarchy-ui 0.0.6-x86_64-linux → 0.0.8-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c8e67a6ee733ab185881c3af8614d428d5888fcea3fed015780ccc4bae6a3b5
-  data.tar.gz: 648c98f47aea9d30e857809a65052bdb2ca374ecaebc122a3ea192b99aa2b815
+  metadata.gz: bbe75336899d8f9674166011c929469db798869f88b32f45a3b61505b0713d01
+  data.tar.gz: bb5f2e4f0dfec4578992d17d5f3fdc5530d5b2c73d4aeebcfada553355077f94
 SHA512:
-  metadata.gz: 5f7664f1dafd992a22872bc029e8c48a242452ad5a8df9185a2aa0707b94b14df8724bd2e8c4fe3bd79afedeaf957e838fb1e27ecabb9467ba0ec41806e8f6d8
-  data.tar.gz: 97ec7a87a20e40653d8247cf69fd2534febb44b89ea7601355ada885d5f1978753332418ae756c9cf2e934a5534d108f43a850eca1c2ef3dc1c741435243d4ea
+  metadata.gz: 9776119537e37548ea84ca4129647a6f94b64944ae75315e776db661220aefeb4cc80527ed93a1b1c9410e0b80d2a547c77a2aae6674f770decc354bdee2a505
+  data.tar.gz: 6856581d58533845967d37daae2679cbf9601f9555aa724b9a9cbf04da0a62a8b15cd146df6d3b36551dec85ad29a13189ba1bdb01a143c2a3cfed87f46d2bb4

data/App.qml

@@ -2,6 +2,7 @@ import QtQuick
 import Quickshell
 import qs.Commons
 import qs.Ui as OmarchyUi
+import "Theme" as ZuiTheme
 
 ShellRoot {
   id: root
@@ -82,7 +83,7 @@ ShellRoot {
         }
       }
 
-      ZuiRenderer {
+      ControlNode {
         id: renderer
         anchors {
           left: parent.left
@@ -91,7 +92,7 @@ ShellRoot {
           bottom: parent.bottom
           margins: Style.space(24)
         }
-        visible: renderReady
+        visible: ZuiTheme.Fonts.ready && root.activeSurface !== "" && service.rootId(root.activeSurface) !== ""
         bridge: service
         surfaceName: root.activeSurface
         controlId: service.rootId(surfaceName)
@@ -103,7 +104,7 @@ ShellRoot {
         anchors.centerIn: parent
         visible: !renderer.visible
         text: service.lastError !== "" ? service.lastError
-          : "Starting Ruby UI with Zui…"
+          : (ZuiTheme.Fonts.failed ? "Omarchy UI could not load Zui's bundled fonts" : "Starting Ruby UI…")
         color: Color.foreground
         font.family: Style.font.family
         font.pixelSize: Style.font.body

data/BarWidget.qml

@@ -1,6 +1,7 @@
 import QtQuick
 import qs.Commons
 import qs.Ui
+import "Theme" as ZuiTheme
 
 BarWidget {
   id: root
@@ -16,10 +17,10 @@ BarWidget {
   implicitWidth: Math.max(Style.bar.iconSlot, renderer.implicitWidth + Style.space(12))
   implicitHeight: barSize
 
-  ZuiRenderer {
+  ControlNode {
     id: renderer
     anchors.centerIn: parent
-    visible: renderReady
+    visible: ZuiTheme.Fonts.ready && root.rubyService && root.rootControlId !== ""
     bridge: root.rubyService
     surfaceName: root.surfaceName
     controlId: root.rootControlId

data/Panel.qml

@@ -3,6 +3,7 @@ import Quickshell
 import Quickshell.Wayland
 import qs.Commons
 import qs.Ui as OmarchyUi
+import "Theme" as ZuiTheme
 
 Item {
   id: root
@@ -77,10 +78,10 @@ Item {
           onClicked: {}
         }
 
-        ZuiRenderer {
+        ControlNode {
           id: renderer
           anchors.centerIn: parent
-          visible: renderReady
+          visible: ZuiTheme.Fonts.ready && root.service && root.rootControlId !== ""
           bridge: root.service
           surfaceName: root.surfaceName
           controlId: root.rootControlId
@@ -97,7 +98,7 @@ Item {
             anchors.horizontalCenter: parent.horizontalCenter
             text: root.service && root.service.lastError !== ""
               ? root.service.lastError
-              : "Starting Ruby UI with Zui…"
+              : (ZuiTheme.Fonts.failed ? "Omarchy UI could not load Zui's bundled fonts" : "Starting Ruby UI…")
             color: Color.foreground
             font.family: Style.font.family
             font.pixelSize: Style.font.body

data/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  <img alt="Omarchy UI 0.0.6" src="https://img.shields.io/badge/Omarchy_UI-0.0.6-b7ff5a?style=flat-square&labelColor=111711">
+  <img alt="Omarchy UI 0.0.8" src="https://img.shields.io/badge/Omarchy_UI-0.0.8-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">
@@ -53,8 +53,8 @@ and the Omarchy adapter.
 
 | Build | Use it for | Primary surface | Delivery |
 | --- | --- | --- | --- |
-| Omarchy application | Full desktop tools and standalone interfaces | `app :main` | `omarchy_ui run` or `omarchy_ui bundle` |
-| Omarchy plugin | Bar widgets, panels, and shell-integrated tools | `bar_widget` and `panel` | `omarchy_ui validate` and `omarchy_ui push` |
+| Omarchy application | Full desktop tools and standalone interfaces | `app :main` | `omarchy_ui new NAME`, then `run` or `bundle` |
+| Omarchy plugin | Bar widgets, panels, and shell-integrated tools | `bar_widget` and `panel` | `omarchy_ui new NAME --plugin`, then `push` or `bundle` |
 | Portable Zui application | The same application UI outside Omarchy | `app :main` | The platform-neutral [Zui toolchain](https://github.com/AdamMusa/zui#developer-workflow) |
 
 ## Requirements
@@ -63,11 +63,11 @@ and the Omarchy adapter.
 - Ruby 3.1 or newer while installing the gem and developing applications;
 - optional Qt modules for components that use features such as Quick 3D or Multimedia.
 
-The finished Omarchy bundle includes the Omarchy adapter and mruby executable. Shared renderers,
-controls, theme, and fonts stay in the compatible Zui gem instead of being duplicated into every
-plugin. The destination therefore needs Ruby and `omarchy-ui` installed. A component fails with an
-explicit error when its gem, required Qt module, or resource is unavailable; Omarchy UI never
-substitutes a different component.
+Omarchy UI generates a complete Omarchy-compatible application or plugin package from the
+developer's Ruby and assets. It owns the Omarchy metadata, entry points, adapter, validation,
+tree-shaken Zui QML, and embedded mruby runtime. The finished package does not need Ruby or framework
+gems. A component fails with an explicit error when its required Qt module or resource is unavailable;
+Omarchy UI never substitutes a different component.
 
 ## Quick start
 
@@ -79,20 +79,37 @@ gem install omarchy-ui
 
 The gem installs the compatible Zui version as a dependency.
 
-### 2. Generate an application
+### 2. Generate a complete project
 
 ```bash
 omarchy_ui new Counter
 cd counter
 ```
 
+For an integrated Omarchy plugin instead:
+
+```bash
+omarchy_ui new "System Status" --plugin
+cd system-status
+```
+
+Both commands create a ready-to-run Ruby project. Omarchy UI generates the complete compliant
+application or plugin package; developers do not write QML, shell entry points, or an Omarchy
+manifest by hand.
+
+Each project includes a Ruby-native `config.rb` containing its type, identity, release version,
+entry point, and—for plugins—public marketplace metadata. `bundle`, `validate`, and `push` read this
+single configuration when assembling the complete package.
+
 The generator creates a small, host-independent project:
 
 ```text
 counter/
+├── LICENSE
 ├── app.rb                  # reusable Zui application
 ├── components/
 │   └── welcome.rb          # application-owned Ruby UI module
+├── config.rb               # project identity and build settings
 ├── main.rb                 # Omarchy launcher
 └── README.md
 ```
@@ -103,7 +120,7 @@ counter/
 omarchy_ui run main.rb
 ```
 
-`run` bundles the project's Ruby entry point, prepares the Omarchy host, resolves the exact Zui gem,
+`run` bundles the project's Ruby entry point, asks Zui to tree-shake the QML runtime, prepares the Omarchy host,
 then launches it through Quickshell.
 
 ## Application model
@@ -229,48 +246,18 @@ QML is not required.
 
 ## Omarchy plugins
 
-A Ruby-powered plugin is an ordinary Omarchy plugin repository with `manifest.json` and `main.rb`
-at its root. Omarchy UI adds the generated service, panel, bar-widget, framework, and runtime files
-while staging the plugin; do not commit generated copies to the application source.
+Generate a complete plugin project with one command:
 
-```text
-system-status/
-├── manifest.json
-├── main.rb
-└── assets/
+```bash
+omarchy_ui new "System Status" --plugin
+cd system-status
 ```
 
-### Manifest
-
-This complete manifest declares the adapter surfaces used by the Ruby definition below:
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "example.system-status",
-  "name": "System Status",
-  "version": "0.1.0",
-  "author": "Example Author",
-  "license": "MIT",
-  "description": "A Ruby-powered status panel for Omarchy.",
-  "kinds": ["service", "bar-widget", "panel"],
-  "keepLoaded": true,
-  "entryPoints": {
-    "service": "Service.qml",
-    "barWidget": "BarWidget.qml",
-    "panel": "Panel.qml"
-  },
-  "barWidget": {
-    "displayName": "System Status",
-    "description": "Open the current system status.",
-    "category": "System",
-    "allowMultiple": false,
-    "defaultSection": "right"
-  }
-}
-```
+The generated project already satisfies Omarchy's structural requirements. Developers work in Ruby
+and add their own assets; Omarchy UI owns the required plugin metadata, shell surfaces, native host,
+tree-shaken Zui package, validation, and install lifecycle.
 
-### Ruby entry point
+The Ruby entry point uses ordinary Zui components:
 
 ```ruby
 # main.rb
@@ -295,35 +282,29 @@ OmarchyUI.plugin do
 end
 ```
 
-`bar_widget` declares the shell-owned bar surface. `panel :status` declares the panel opened by
-`open_panel :status`. The manifest must declare the corresponding entry points.
+`bar_widget` and `panel :status` are the complete developer-facing surface declarations. Omarchy UI
+maps them to the required Omarchy shell entry points when it builds or stages the plugin.
 
 ### Validate and install
 
 ```bash
-omarchy_ui validate path/to/system-status
-omarchy_ui push path/to/system-status
+omarchy_ui validate
+omarchy_ui push
 ```
 
-`validate` checks a fully staged copy, including the bundled Ruby entry point and generated adapter.
-`push` then:
-
-1. stages and validates the complete plugin;
-2. backs up an existing installation when present;
-3. installs it atomically under `~/.config/omarchy/plugins/<plugin-id>`;
-4. enables the plugin; and
-5. restarts the Omarchy shell.
+`validate` generates and checks the complete plugin without mutating the Ruby project. `push` safely
+builds, validates, installs, enables, and reloads the plugin for development.
 
 During development, suppress either lifecycle action when needed:
 
 ```bash
-omarchy_ui push path/to/system-status --no-enable
-omarchy_ui push path/to/system-status --no-restart
+omarchy_ui push --no-enable
+omarchy_ui push --no-restart
 ```
 
 > [!WARNING]
 > Omarchy plugins execute as unsandboxed user code inside the shell environment. Review the Ruby,
-> assets, manifest, generated package, and provenance before installing a third-party plugin.
+> assets, generated package, and provenance before installing a third-party plugin.
 
 ## Command-line reference
 
@@ -333,9 +314,10 @@ omarchy_ui <command> [arguments]
 
 | Command | Arguments | Result |
 | --- | --- | --- |
-| `omarchy_ui new NAME` | One application name | Creates a new application directory using a URL-safe form of the name |
+| `omarchy_ui new NAME` | One project name | Creates a complete Omarchy application project |
+| `omarchy_ui new NAME --plugin` | One project name and `--plugin` | Creates a complete Omarchy-compliant 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 | Creates `dist/<project-name>` with the application, Omarchy adapter, and runtime; shared UI comes from Zui |
+| `omarchy_ui bundle [DIRECTORY]` | Zero or one project directory | Generates the complete distributable package and prints its location |
 | `omarchy_ui validate [DIRECTORY]` | Zero or one plugin directory | Stages the complete 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 |
@@ -345,36 +327,19 @@ not forward arbitrary Ruby arguments.
 
 ## Packaging
 
-Create a distributable application from the project root:
+Create the complete distributable package from the project root:
 
 ```bash
 omarchy_ui bundle
-./dist/my-application/run
-```
-
-The bundle contains:
-
-```text
-dist/my-application/
-├── main.rb                     # bundled application source
-├── assets/                     # application-owned resources
-├── App.qml                     # Omarchy host entry point
-├── Service.qml                 # process and surface bridge
-├── Panel.qml                   # shell panel adapter
-├── BarWidget.qml               # shell bar adapter
-├── ZuiRenderer.qml             # resolves Zui's shared protocol renderer
-├── Commons@ Ui@                # links to Omarchy's shell modules
-├── omarchy-ui-runtime          # embedded mruby executable
-├── omarchy-ui-runtime.sha256
-├── RUNTIME_PROVENANCE.md
-└── run
 ```
 
-Plugin bundles use the same runtime package and are validated against their manifest before the
-bundle command succeeds. Generated packages exclude `.git`, previous `dist` output, stale
-adapter/runtime files, and every Zui-owned QML directory. Install `omarchy-ui` on the destination so
-RubyGems supplies the exact Zui 0.0.10 catalog once for every plugin. The exact pin intentionally
-matches the Zui core embedded in the deterministic mruby runtime.
+Omarchy UI prints the generated package location. It automatically assembles the bundled Ruby and
+assets, Omarchy metadata and entry points, native host, checksummed runtime provenance, and only the
+Zui QML components used by the project. Application packages receive a direct launcher; plugin
+packages are validated against Omarchy's requirements before the command succeeds. Omarchy UI pins
+Zui 0.0.10 so generated QML exactly matches the Zui core embedded in the deterministic mruby runtime.
+The source `config.rb` remains the authoritative build configuration; plugin manifests are generated
+from it in the distributable package and are never maintained separately by the developer.
 
 ## Component catalog
 
@@ -461,10 +426,10 @@ The dependency direction is deliberate:
   integration, plugin lifecycle commands, and Omarchy packaging.
 - **Applications own** Ruby source, assets, state, behavior, and reusable UI modules.
 
-At runtime, the adapter locates the compatible Zui gem and loads its protocol renderer, components,
-controls, theme, and fonts directly from `Zui::FRAMEWORK_ROOT`. Bundle, validation, and push install
-only the Omarchy host files and never copy Zui component implementations into an application or
-plugin. Read the full [QML ownership and adapter boundary](docs/qml-support.md).
+At bundle, validation, and push time, Omarchy UI asks Zui to analyze the bundled Ruby syntax and
+generate only the required component adapters plus their renderer dependencies. The four Omarchy
+host files then replace Zui's generic desktop host. Read the full [QML ownership and adapter
+boundary](docs/qml-support.md).
 
 ## Runtime integrity
 
@@ -503,11 +468,11 @@ bodies are never recorded. Per-plugin logs rotate at 128 KiB under
 | `Ruby file not found` | Pass an existing entry point to `omarchy_ui run`, normally `main.rb` |
 | `Omarchy QML module not found` | Confirm the Omarchy shell installation provides `/usr/share/omarchy/shell/Commons` and `Ui` |
 | A component reports a missing module | Install or enable the Qt module required by that declared component |
-| Plugin validation fails | Run `omarchy_ui validate` and correct the manifest or staged project error before pushing |
+| Plugin validation fails | Run `omarchy_ui validate` and correct the reported Ruby, asset, or generated-metadata error before pushing |
 | A pushed plugin is installed but inactive | Run `omarchy plugin enable <id>` and `omarchy restart shell` after resolving the reported shell error |
-| The bundle destination already exists | Review or move the existing `dist/<project-name>` directory before bundling again |
+| The bundle destination already exists | Review or move the previously generated package before bundling again |
 
-Omarchy UI reports unsupported properties, components, events, paths, manifests, and runtime
+Omarchy UI reports unsupported properties, components, events, paths, generated metadata, and runtime
 resources directly. Preserve the original error when opening an issue.
 
 ## Development

data/Service.qml

@@ -14,11 +14,6 @@ Item {
   readonly property string rubyProgram: pluginDir + "/main.rb"
   property string program: ""
   readonly property string effectiveRubyProgram: program !== "" ? program : rubyProgram
-  readonly property string requiredZuiVersion: "0.0.10"
-  property string zuiRoot: ""
-  property string zuiVersion: ""
-  readonly property bool zuiReady: zuiRoot !== ""
-
   property bool ready: false
   property bool stopping: false
   property string lastError: ""
@@ -418,7 +413,7 @@ Item {
 
   function componentSource(typeName) {
     var definition = componentDefinitions[String(typeName || "")]
-    return definition && zuiReady ? zuiRoot + "/Components/Builtins/" + definition.qml : ""
+    return definition ? pluginDir + "/Components/Builtins/" + definition.qml : ""
   }
 
   function componentDefinition(typeName) {
@@ -446,7 +441,7 @@ Item {
   }
 
   function startRuby() {
-    if (stopping || pluginDir === "" || !zuiReady || rubyProcess.running) return
+    if (stopping || pluginDir === "" || rubyProcess.running) return
     var configuredRuntime = String(Quickshell.env("OMARCHY_UI_RUNTIME") || "")
     rubyProcess.command = [
       configuredRuntime !== "" ? configuredRuntime : pluginDir + "/omarchy-ui-runtime",
@@ -456,68 +451,14 @@ Item {
     rubyProcess.running = true
   }
 
-  function locateZui() {
-    if (stopping || pluginDir === "" || zuiReady || zuiLocator.running) return
-    zuiLocator.command = [
-      "ruby", "-e",
-      'require "json"; gem "zui", "= ' + requiredZuiVersion
-        + '"; require "zui"; STDOUT.write(JSON.generate({root: Zui::FRAMEWORK_ROOT, version: Zui::VERSION}))'
-    ]
-    zuiLocator.running = true
-  }
-
-  onPluginDirChanged: {
-    zuiRoot = ""
-    zuiVersion = ""
-    Qt.callLater(locateZui)
-  }
-
-  Component.onCompleted: Qt.callLater(locateZui)
+  onPluginDirChanged: Qt.callLater(startRuby)
 
   Component.onDestruction: {
     stopping = true
     restartTimer.stop()
-    if (zuiLocator.running) zuiLocator.running = false
     if (rubyProcess.running) rubyProcess.running = false
   }
 
-  Process {
-    id: zuiLocator
-
-    stdout: StdioCollector {
-      id: zuiLocatorOutput
-      waitForEnd: true
-    }
-
-    stderr: StdioCollector {
-      id: zuiLocatorError
-      waitForEnd: true
-    }
-
-    onExited: function(exitCode) {
-      if (root.stopping || root.pluginDir === "") return
-      var detail = String(zuiLocatorError.text || "").trim()
-      if (exitCode !== 0) {
-        root.lastError = "Zui " + root.requiredZuiVersion
-          + " is required from the omarchy-ui gem"
-          + (detail !== "" ? ": " + detail.slice(0, 240) : "")
-        return
-      }
-      try {
-        var located = JSON.parse(String(zuiLocatorOutput.text || ""))
-        if (!located || typeof located.root !== "string" || located.root[0] !== "/"
-            || String(located.version || "") !== root.requiredZuiVersion)
-          throw new Error("invalid Zui gem location")
-        root.zuiRoot = String(located.root)
-        root.zuiVersion = String(located.version)
-        root.lastError = ""
-        root.startRuby()
-      } catch (error) {
-        root.lastError = "Could not locate Zui " + root.requiredZuiVersion + " from RubyGems"
-      }
-    }
-  }
-
   Process {
     id: rubyProcess
     stdinEnabled: true

data/lib/omarchy_ui/cli.rb

@@ -27,7 +27,7 @@ module OmarchyUI
       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|bundle [DIRECTORY]|push [DIRECTORY]|validate [DIRECTORY]|version>")
+        @err.puts("Usage: omarchy_ui <new NAME [--plugin]|run FILE|bundle [DIRECTORY]|push [DIRECTORY]|validate [DIRECTORY]|version>")
         command.nil? ? 0 : 64
       end
     rescue Interrupt
@@ -67,14 +67,30 @@ module OmarchyUI
     end
 
     def new_project(arguments)
+      plugin = !arguments.delete("--plugin").nil?
       name = arguments.shift || raise(ArgumentError, "new requires a project name")
-      raise ArgumentError, "new accepts only an application name" unless arguments.empty?
+      raise ArgumentError, "new accepts a name and optional --plugin" unless arguments.empty?
       destination = File.expand_path(slug(name))
-      Generator.new(path: destination, name: name).create
-      @out.puts("Created standalone Omarchy UI app in #{destination}")
+      kind = plugin ? :plugin : :application
+      Generator.new(path: destination, name: name, kind:, author: default_author).create
+      label = plugin ? "Omarchy-compliant plugin" : "self-contained Omarchy application"
+      @out.puts("Created #{label} in #{destination}")
       0
     end
 
+    def default_author
+      configured = ENV["OMARCHY_UI_AUTHOR"].to_s.strip
+      return configured unless configured.empty?
+
+      output, _error, status = Open3.capture3("git", "config", "--get", "user.name")
+      git_author = output.to_s.strip
+      return git_author if status.success? && !git_author.empty?
+
+      ENV["USER"].to_s.strip.then { |user| user.empty? ? "Omarchy UI Developer" : user }
+    rescue SystemCallError
+      "Omarchy UI Developer"
+    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?
@@ -83,6 +99,10 @@ module OmarchyUI
 
     def validate(arguments)
       source = File.expand_path(arguments.shift || Dir.pwd)
+      raise ArgumentError, "validate accepts one directory" unless arguments.empty?
+      config = ProjectConfig.load(source)
+      raise ArgumentError, "validate requires a plugin project" if config&.application?
+
       with_staged_project(source) do |staging|
         system("omarchy", "plugin", "validate", staging) ? 0 : 1
       end
@@ -91,15 +111,19 @@ module OmarchyUI
     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))
+      config = ProjectConfig.load(source)
+      entrypoint = config&.entrypoint || "main.rb"
+      raise ArgumentError, "#{entrypoint} not found: #{source}" unless File.file?(File.join(source, entrypoint))
+      destination = File.join(source, "dist", config&.slug || File.basename(source))
       raise ArgumentError, "bundle destination already exists: #{destination}" if File.exist?(destination)
       FileUtils.mkdir_p(destination)
-      entries = application_entries(source)
+      entries = application_entries(source, config:)
       FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, destination)
-      bundle_ruby_entrypoint(source, destination)
+      config.write_manifest(destination) if config&.plugin?
+      bundle_ruby_entrypoint(source, destination, entrypoint:)
       Runtime.install_package(destination)
-      if File.file?(File.join(destination, "manifest.json"))
+      plugin = config ? config.plugin? : File.file?(File.join(destination, "manifest.json"))
+      if plugin
         raise ArgumentError, "bundled plugin validation failed" unless system("omarchy", "plugin", "validate", destination)
         @out.puts("Bundled plugin in #{destination}")
         return 0
@@ -115,7 +139,7 @@ module OmarchyUI
         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"
+        export OMARCHY_UI_RUBY_PROGRAM="$app_dir/#{entrypoint}"
         export QT_LOGGING_RULES="${QT_LOGGING_RULES:+$QT_LOGGING_RULES;}qt.qpa.services.warning=false"
         exec quickshell --path "$app_dir/App.qml"
       SH
@@ -131,8 +155,9 @@ module OmarchyUI
       [ENV["QT_LOGGING_RULES"], "qt.qpa.services.warning=false"].compact.reject(&:empty?).join(";")
     end
 
-    def application_entries(source)
+    def application_entries(source, config: ProjectConfig.load(source))
       generated = Runtime::GENERATED_ENTRIES + Runtime::AUDIT_FILES + %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) }
     end
 
@@ -140,8 +165,11 @@ module OmarchyUI
       enable = !arguments.delete("--no-enable")
       restart = !arguments.delete("--no-restart")
       source = File.expand_path(arguments.shift || Dir.pwd)
+      raise ArgumentError, "push accepts one directory" unless arguments.empty?
+      config = ProjectConfig.load(source)
+      raise ArgumentError, "push requires a plugin project" if config&.application?
       manifest_path = File.join(source, "manifest.json")
-      manifest = JSON.parse(File.read(manifest_path))
+      manifest = config ? config.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")
@@ -184,11 +212,14 @@ module OmarchyUI
 
     def stage_project(source, parent: nil, prefix: ".omarchy-ui-staging-")
       raise ArgumentError, "project directory not found: #{source}" unless File.directory?(source)
+      config = ProjectConfig.load(source)
       staging = parent ? Dir.mktmpdir(prefix, parent) : Dir.mktmpdir(prefix)
-      entries = application_entries(source)
+      entries = application_entries(source, config:)
       FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, staging) unless entries.empty?
-      if File.file?(File.join(staging, "main.rb"))
-        bundle_ruby_entrypoint(source, staging)
+      config.write_manifest(staging) if config&.plugin?
+      entrypoint = config&.entrypoint || "main.rb"
+      if File.file?(File.join(staging, entrypoint))
+        bundle_ruby_entrypoint(source, staging, entrypoint:)
         Runtime.install_package(staging)
       end
       staging
@@ -197,9 +228,11 @@ module OmarchyUI
       raise
     end
 
-    def bundle_ruby_entrypoint(source, destination)
-      entrypoint = File.join(source, "main.rb")
-      File.write(File.join(destination, "main.rb"), SourceBundle.new(entrypoint, root: source).call)
+    def bundle_ruby_entrypoint(source, destination, entrypoint: "main.rb")
+      source_entrypoint = File.join(source, entrypoint)
+      destination_entrypoint = File.join(destination, entrypoint)
+      FileUtils.mkdir_p(File.dirname(destination_entrypoint))
+      File.write(destination_entrypoint, SourceBundle.new(source_entrypoint, root: source).call)
     end
 
     def activate_plugin(plugin_id)

data/lib/omarchy_ui/generator.rb

@@ -4,9 +4,15 @@ require "fileutils"
 
 module OmarchyUI
   class Generator
-    def initialize(path:, name: nil)
+    PROJECT_KINDS = %i[application plugin].freeze
+
+    def initialize(path:, name: nil, kind: :application, plugin_id: nil, author: 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}"
+      @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
 
     def create
@@ -14,9 +20,11 @@ module OmarchyUI
       created = true
       FileUtils.mkdir_p(File.join(@path, "components"))
       File.write(File.join(@path, "main.rb"), main_program)
-      File.write(File.join(@path, "app.rb"), application_program)
+      File.write(File.join(@path, "app.rb"), application_program) unless plugin?
+      File.write(File.join(@path, ProjectConfig::FILE_NAME), project_config)
       File.write(File.join(@path, "components", "welcome.rb"), welcome_component)
       File.write(File.join(@path, "README.md"), readme)
+      File.write(File.join(@path, "LICENSE"), license)
       @path
     rescue StandardError
       FileUtils.remove_entry(@path) if created && File.directory?(@path)
@@ -26,6 +34,8 @@ module OmarchyUI
     private
 
     def main_program
+      return plugin_program if plugin?
+
       <<~RUBY
         # frozen_string_literal: true
 
@@ -36,6 +46,33 @@ module OmarchyUI
       RUBY
     end
 
+    def plugin_program
+      <<~RUBY
+        # frozen_string_literal: true
+
+        require "omarchy_ui"
+        require_relative "components/welcome"
+
+        OmarchyUI.plugin(ui: #{constant_name}::UI) do
+          bar_widget do
+            row spacing: 7 do
+              text "#{@name}"
+            end
+            on_click { open_panel :#{surface_name} }
+          end
+
+          panel :#{surface_name} do
+            scroll width: 560, height: 620 do
+              welcome_card(
+                title: "#{@name}",
+                message: "Your Omarchy plugin is ready. Build the interface with Ruby and Zui components."
+              )
+            end
+          end
+        end
+      RUBY
+    end
+
     def application_program
       <<~RUBY
         # frozen_string_literal: true
@@ -80,6 +117,8 @@ module OmarchyUI
     end
 
     def readme
+      return plugin_readme if plugin?
+
       <<~MARKDOWN
         # #{@name}
 
@@ -92,10 +131,97 @@ module OmarchyUI
         ```
 
         Reusable Ruby UI components live in `components/` and load with ordinary Ruby
-        `require_relative`. Run `omarchy_ui bundle` to create a self-contained distribution.
+        `require_relative`. Project identity and build settings live in `config.rb`.
+
+        ## Build
+
+        ```bash
+        omarchy_ui bundle
+        ```
+
+        Omarchy UI generates the complete self-contained application package required by Omarchy.
+      MARKDOWN
+    end
+
+    def plugin_readme
+      <<~MARKDOWN
+        # #{@name}
+
+        A pure Ruby Omarchy plugin built with Omarchy UI and Zui.
+
+        ## Validate
+
+        ```bash
+        omarchy_ui validate
+        ```
+
+        ## Install for development
+
+        ```bash
+        omarchy_ui push
+        ```
+
+        ## Build
+
+        ```bash
+        omarchy_ui bundle
+        ```
+
+        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 uses it to
+        generate and validate the complete Omarchy-compatible plugin package.
       MARKDOWN
     end
 
+    def project_config
+      config = ProjectConfig.generate(
+        name: @name,
+        slug: project_slug,
+        kind: @kind,
+        author: @author,
+        plugin_id: @plugin_id
+      )
+      config
+    end
+
+    def license
+      <<~TEXT
+        MIT License
+
+        Copyright (c) #{Time.now.year} #{@author}
+
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+      TEXT
+    end
+
+    def plugin?
+      @kind == :plugin
+    end
+
+    def project_slug
+      File.basename(@path).downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|\-\z/, "")
+    end
+
+    def surface_name
+      project_slug.tr("-", "_")
+    end
+
     def constant_name
       @name.gsub(/[^a-zA-Z0-9]+/, " ").split.map(&:capitalize).join.then do |name|
         name.empty? || name.match?(/\A\d/) ? "OmarchyApplication" : name

data/lib/omarchy_ui/project_config.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OmarchyUI
+  class ProjectConfig
+    FILE_NAME = "config.rb"
+    PROJECT_TYPES = %i[application plugin].freeze
+    SLUG = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+    SECTIONS = %i[left center right].freeze
+
+    class Builder
+      FIELDS = %i[type id name slug version author license description entrypoint].freeze
+
+      FIELDS.each do |field|
+        define_method(field) { |value| @values[field] = value }
+      end
+
+      def initialize
+        @values = {}
+      end
+
+      def bar_widget(&definition)
+        widget = WidgetBuilder.new
+        widget.instance_eval(&definition)
+        @values[:bar_widget] = widget.to_h
+      end
+
+      def build(path: FILE_NAME)
+        ProjectConfig.new(@values, path:).tap(&:validate!)
+      end
+    end
+
+    class WidgetBuilder
+      FIELDS = %i[display_name description category default_section].freeze
+
+      FIELDS.each do |field|
+        define_method(field) { |value| @values[field] = value }
+      end
+
+      def initialize
+        @values = {}
+      end
+
+      def to_h
+        @values.dup
+      end
+    end
+
+    attr_reader :path
+
+    def self.define(&definition)
+      raise ArgumentError, "project config requires a block" unless definition
+
+      Builder.new.tap { |builder| builder.instance_eval(&definition) }.build
+    end
+
+    def self.generate(name:, slug:, kind:, author:, plugin_id: nil)
+      type = kind.to_sym
+      raise ArgumentError, "unsupported project type: #{type}" unless PROJECT_TYPES.include?(type)
+
+      lines = [
+        "# frozen_string_literal: true",
+        "",
+        "OmarchyUI.configure do",
+        "  type #{type.inspect}"
+      ]
+      lines << "  id #{(plugin_id || "local.#{slug}").inspect}" if type == :plugin
+      lines.concat([
+        "  name #{name.inspect}",
+        "  slug #{slug.inspect}",
+        "  version \"0.1.0\""
+      ])
+      if type == :plugin
+        lines.concat([
+          "  author #{author.inspect}",
+          "  license \"MIT\"",
+          "  description #{"A Ruby-powered #{name} plugin generated by Omarchy UI.".inspect}",
+          "  entrypoint \"main.rb\"",
+          "",
+          "  bar_widget do",
+          "    display_name #{name.inspect}",
+          "    description #{"Open #{name}.".inspect}",
+          "    category \"System\"",
+          "    default_section :right",
+          "  end"
+        ])
+      else
+        lines << "  entrypoint \"main.rb\""
+      end
+      lines << "end"
+      lines.join("\n") + "\n"
+    end
+
+    def self.load(root)
+      path = File.join(File.expand_path(root), FILE_NAME)
+      return nil unless File.file?(path)
+
+      value = Module.new.module_eval(File.read(path), path, 1)
+      unless value.is_a?(ProjectConfig)
+        raise ArgumentError, "#{FILE_NAME} must return an OmarchyUI::ProjectConfig"
+      end
+
+      new(value.to_h, path:).tap(&:validate!)
+    rescue SyntaxError, NameError, NoMethodError => error
+      raise ArgumentError, "invalid #{FILE_NAME}: #{error.message}"
+    end
+
+    def initialize(data, path:)
+      @data = data
+      @path = path
+    end
+
+    def type
+      value = @data[:type]
+      value.respond_to?(:to_sym) ? value.to_sym : value
+    end
+    def application? = type == :application
+    def plugin? = type == :plugin
+    def name = @data.fetch(:name)
+    def slug = @data.fetch(:slug)
+    def entrypoint = @data.fetch(:entrypoint)
+
+    def to_h
+      @data.dup
+    end
+
+    def manifest
+      raise ArgumentError, "project config describes an application, not a plugin" unless plugin?
+
+      widget = @data.fetch(:bar_widget)
+      {
+        "schemaVersion" => 1,
+        "id" => @data.fetch(:id),
+        "name" => name,
+        "version" => @data.fetch(:version),
+        "author" => @data.fetch(:author),
+        "license" => @data.fetch(:license),
+        "description" => @data.fetch(:description),
+        "kinds" => ["service", "bar-widget", "panel"],
+        "keepLoaded" => true,
+        "entryPoints" => {
+          "service" => "Service.qml",
+          "barWidget" => "BarWidget.qml",
+          "panel" => "Panel.qml"
+        },
+        "barWidget" => {
+          "displayName" => widget.fetch(:display_name),
+          "description" => widget.fetch(:description),
+          "category" => widget.fetch(:category),
+          "allowMultiple" => false,
+          "defaultSection" => widget.fetch(:default_section).to_s
+        }
+      }
+    end
+
+    def write_manifest(destination)
+      File.write(File.join(destination, "manifest.json"), JSON.pretty_generate(manifest) + "\n")
+    end
+
+    def validate!
+      raise ArgumentError, "invalid project config" unless @data.is_a?(Hash)
+      raise ArgumentError, "invalid project type" unless PROJECT_TYPES.include?(type)
+      required_string!(:name)
+      required_string!(:slug)
+      raise ArgumentError, "invalid project slug" unless SLUG.match?(@data[:slug])
+      required_string!(:version)
+      required_string!(:entrypoint)
+      validate_entrypoint!
+      validate_plugin! if plugin?
+      self
+    end
+
+    private
+
+    def required_string!(key, object = @data)
+      value = object[key]
+      raise ArgumentError, "invalid project config field: #{key}" unless value.is_a?(String) && !value.strip.empty?
+
+      value
+    end
+
+    def validate_entrypoint!
+      parts = entrypoint.split(/[\\\/]/)
+      if entrypoint.start_with?("/") || parts.empty? || parts.include?("..") || !entrypoint.end_with?(".rb")
+        raise ArgumentError, "invalid project entrypoint"
+      end
+    end
+
+    def validate_plugin!
+      %i[id author license description].each { |key| required_string!(key) }
+      raise ArgumentError, "invalid plugin id" unless VALID_ID.match?(@data[:id])
+
+      widget = @data[:bar_widget]
+      raise ArgumentError, "plugin project config is missing bar widget metadata" unless widget.is_a?(Hash)
+
+      %i[display_name description category].each { |key| required_string!(key, widget) }
+      section = widget[:default_section]
+      valid_section = section.respond_to?(:to_sym) && SECTIONS.include?(section.to_sym)
+      raise ArgumentError, "invalid default bar section" unless valid_section
+    end
+  end
+
+  def self.configure(&definition)
+    ProjectConfig.define(&definition)
+  end
+end

data/lib/omarchy_ui/runtime.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
+require "tmpdir"
 
 module OmarchyUI
   module Runtime
     module_function
 
     BUNDLED = File.expand_path("../../vendor/runtime/x86_64-linux/omarchy-ui-runtime", __dir__)
-    ADAPTER_FILES = %w[Service.qml Panel.qml BarWidget.qml App.qml ZuiRenderer.qml].freeze
+    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
-    FILES = ADAPTER_FILES.freeze
+    TREE_SHAKE_REPORT = "zui-tree-shake.json"
+    FILES = (ADAPTER_FILES + %w[ControlNode.qml]).freeze
     AUDIT_FILES = %w[
       omarchy-ui-runtime.sha256 runtime-provenance.json RUNTIME_PROVENANCE.md
     ].freeze
-    GENERATED_ENTRIES = (ADAPTER_FILES + ZUI_GENERATED_ENTRIES + %w[omarchy-ui-runtime]).freeze
+    GENERATED_ENTRIES = (ADAPTER_FILES + ZUI_GENERATED_ENTRIES +
+      [TREE_SHAKE_REPORT, "omarchy-ui-runtime"]).freeze
 
     def executable
       override = ENV["OMARCHY_UI_RUNTIME"]
@@ -35,15 +39,24 @@ module OmarchyUI
       FileUtils.rm_f(temporary) if temporary && File.exist?(temporary)
     end
 
-    def install_package(path, framework_root: FRAMEWORK_ROOT)
+    def install_package(path, framework_root: FRAMEWORK_ROOT, project: path)
       FileUtils.mkdir_p(path)
-      ZUI_GENERATED_ENTRIES.each do |entry|
+      GENERATED_ENTRIES.each do |entry|
         generated = File.join(path, entry)
         File.directory?(generated) ? FileUtils.remove_entry(generated) : FileUtils.rm_f(generated)
       end
+      report = 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")
@@ -57,8 +70,22 @@ module OmarchyUI
       path
     end
 
-    def install_components(path, **)
-      install_package(path)
+    def install_components(path, **options)
+      install_package(path, **options)
+    end
+
+    def install_tree_shaken_zui(destination, project:)
+      Dir.mktmpdir("omarchy-ui-zui-") do |temporary|
+        qml = File.join(temporary, "qml")
+        native = File.join(temporary, "native")
+        FileUtils.mkdir_p(native)
+        Zui::Runtime.install_qml(qml)
+        report = Zui::TreeShaker.new(project:, framework: qml, native:).shake!
+        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
   end
 end

data/lib/omarchy_ui.rb

@@ -11,7 +11,7 @@ rescue LoadError
 end
 
 module OmarchyUI
-  VERSION = "0.0.6"
+  VERSION = "0.0.8"
   ZUI_VERSION = Zui::VERSION
   FRAMEWORK_ROOT = File.expand_path("..", __dir__)
 
@@ -126,5 +126,6 @@ module Zui
   end
 end
 
+require_relative "omarchy_ui/project_config"
 require_relative "omarchy_ui/generator"
 require_relative "omarchy_ui/runtime"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omarchy-ui
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: x86_64-linux
 authors:
 - Adam Moussa Ali
@@ -35,11 +35,11 @@ files:
 - Panel.qml
 - README.md
 - Service.qml
-- ZuiRenderer.qml
 - bin/omarchy_ui
 - lib/omarchy_ui.rb
 - lib/omarchy_ui/cli.rb
 - lib/omarchy_ui/generator.rb
+- lib/omarchy_ui/project_config.rb
 - lib/omarchy_ui/runtime.rb
 - vendor/runtime/x86_64-linux/RUNTIME_PROVENANCE.md
 - vendor/runtime/x86_64-linux/omarchy-ui-runtime

data/ZuiRenderer.qml

@@ -1,37 +0,0 @@
-import QtQuick
-
-Loader {
-  id: root
-
-  property var bridge: null
-  property string surfaceName: ""
-  property string controlId: ""
-  property color foreground: "white"
-  property string fontFamily: ""
-  readonly property bool renderReady: status === Loader.Ready && item !== null
-    && String(item.iconFontFamily || "") !== ""
-    && String(item.brandIconFontFamily || "") !== ""
-
-  active: bridge !== null && bridge.zuiReady && controlId !== ""
-  source: active ? bridge.zuiRoot + "/ControlNode.qml" : ""
-
-  function syncRenderer() {
-    if (!item) return
-    item.bridge = bridge
-    item.surfaceName = surfaceName
-    item.controlId = controlId
-    item.foreground = foreground
-    item.fontFamily = fontFamily
-  }
-
-  onLoaded: syncRenderer()
-  onBridgeChanged: syncRenderer()
-  onSurfaceNameChanged: syncRenderer()
-  onControlIdChanged: syncRenderer()
-  onForegroundChanged: syncRenderer()
-  onFontFamilyChanged: syncRenderer()
-  onStatusChanged: {
-    if (status === Loader.Error && bridge)
-      bridge.lastError = "Could not load Zui " + bridge.requiredZuiVersion + " renderer from its gem"
-  }
-}