Salastil/DankMaterialShell

Fork 0

mirror of https://github.com/AvengeMedia/DankMaterialShell.git synced 2026-04-04 04:42:05 -04:00

Files

purian23 5f2a5a5d7d distro: Update DMS/OBS versioning

2026-01-31 20:20:19 -05:00

44 KiB

Raw Blame History

AGENTS.md

This file provides guidance to AI coding assistants.

AI Guidance

After receiving tool results, carefully reflect on their quality and determine optimal next steps before proceeding. Use your thinking to plan and iterate based on this new information, and then take the best next action.
For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
Before you finish, please verify your solution
Do what has been asked; nothing more, nothing less.
NEVER create files unless they're absolutely necessary for achieving your goal.
ALWAYS prefer editing an existing file to creating a new one.
NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
When you update or modify core context files, also update markdown documentation and memory bank
When asked to commit changes, exclude CLAUDE.md and CLAUDE-*.md referenced memory bank system files from any commits.

Memory Bank System

This project uses a structured memory bank system with specialized context files. Always check these files for relevant information before starting work:

Core Context Files

CLAUDE-activeContext.md - Current session state, goals, and progress (if exists)
CLAUDE-patterns.md - Established code patterns and conventions (if exists)
CLAUDE-decisions.md - Architecture decisions and rationale (if exists)
CLAUDE-troubleshooting.md - Common issues and proven solutions (if exists)
CLAUDE-config-variables.md - Configuration variables reference (if exists)
CLAUDE-temp.md - Temporary scratch pad (only read when referenced)

Important: Always reference the active context file first to understand what's currently being worked on and maintain session continuity.

Memory Bank System Backups

When asked to backup Memory Bank System files, you will copy the core context files above and @.claude settings directory to directory @/path/to/backup-directory. If files already exist in the backup directory, you will overwrite them.

Project Overview

DankMaterialShell is a complete desktop environment for Wayland compositors, built as a monorepo with two main components:

1. Go Backend (core/) - System integration, IPC server, and CLI tools (~118,000 lines) 2. QML Frontend (quickshell/) - UI layer consuming the backend's IPC API

Architecture: The Go backend provides all system integration via IPC (Inter-Process Communication), while QML services act as thin wrappers that communicate with the backend. This separation allows for robust system integration while maintaining a reactive, modern UI.

Compositor Support: Niri, Hyprland, MangoWC, Sway, labwc, Scroll (6 compositors supported) Distribution Support: Arch, Fedora, Debian, Ubuntu, openSUSE, Gentoo (6 distributions supported)

Technology Stack

Backend (core/)

Go 1.24+ - System integration and backend services
Wayland Protocols - Display management, screenshots, clipboard, workspaces
D-Bus - Bluetooth, NetworkManager, systemd-logind, desktop portals
IPC Server - Unix socket JSON API for QML ↔ Go communication
CLI Tools - dms command with 20+ subcommands, dankinstall TUI installer

Frontend (quickshell/)

QML (Qt Modeling Language) - UI components and visual presentation
Quickshell Framework - QML-based desktop shell framework
Qt/QtQuick - UI rendering and controls
Matugen - Dynamic theming system for wallpaper-based colors

Development Commands

Backend (Go)

cd core/

# Build
make                 # Build dms CLI (bin/dms)
make dankinstall     # Build installer (bin/dankinstall)
make test            # Run tests
make dist            # Build distribution binaries (no update/greeter features)

# Install
sudo make install    # Install to /usr/local/bin/dms

# Development
gofmt -w .           # Format Go code
go mod tidy          # Clean up dependencies
golangci-lint run    # Run linter

# Run dms CLI
./bin/dms run        # Start shell via dms daemon
./bin/dms ipc <cmd>  # Send IPC command to running shell
./bin/dms --help     # View all commands

Frontend (QML)

cd quickshell/

# Run the shell (requires dms backend running or use 'dms run')
quickshell -p shell.qml
qs -p .              # Shorthand
qs -v -p shell.qml   # Verbose debugging

# Code formatting and linting
qmlfmt -t 4 -i 4 -b 250 -w /path/to/file.qml  # Format QML (don't use qmlformat)
qmllint **/*.qml     # Lint all QML files
./qmlformat-all.sh   # Format all QML files

Architecture Overview

Monorepo Structure

The project is organized as a monorepo with clear separation between backend and frontend:

DankMaterialShell/
├── core/               # Go backend (~118,000 lines)
│   ├── cmd/            # Binary entrypoints
│   │   ├── dms/        # Main CLI with 20+ commands
│   │   └── dankinstall/# TUI installer
│   ├── internal/       # System integration packages (23 packages)
│   │   ├── clipboard/  # Clipboard history (ext-data-control-v1)
│   │   ├── colorpicker/# Native Wayland color picker
│   │   ├── screenshot/ # Screen capture functionality
│   │   ├── brightness/ # DDC/CI & backlight control
│   │   ├── bluez/      # Bluetooth D-Bus integration
│   │   ├── config/     # Configuration management
│   │   ├── dank16/     # Terminal color scheme generator
│   │   ├── deps/       # Dependency detection
│   │   ├── distros/    # Distribution-specific installers (6 distros)
│   │   ├── greeter/    # Display manager greeter
│   │   ├── keybinds/   # Compositor keybind management
│   │   ├── matugen/    # Matugen integration
│   │   ├── notify/     # Notification daemon
│   │   ├── plugins/    # Plugin registry & management
│   │   ├── screenshot/ # Screenshot utilities
│   │   ├── server/     # IPC server with 15+ submodules
│   │   ├── themes/     # Theme registry
│   │   ├── wayland/    # Wayland protocol handlers
│   │   └── windowrules/# Window rules management
│   ├── pkg/            # Shared packages
│   │   ├── go-wayland/ # Wayland client library
│   │   ├── dbusutil/   # D-Bus utilities
│   │   ├── ipp/        # Internet Printing Protocol
│   │   └── syncmap/    # Thread-safe map
│   └── go.mod          # Go module definition
├── quickshell/         # QML frontend (UI layer) - see "QML Frontend Architecture" below
│   ├── shell.qml       # Main entry point
│   ├── Services/       # IPC client wrappers
│   ├── Modules/        # UI components
│   ├── Widgets/        # Reusable controls
│   ├── Modals/         # Full-screen overlays
│   └── Common/         # Shared resources
├── distro/             # Distribution packaging
│   ├── arch/           # AUR packages
│   ├── fedora/         # RPM specs
│   ├── debian/         # Debian packaging
│   ├── ubuntu/         # Ubuntu PPAs
│   ├── opensuse/       # OBS packaging
│   └── nix/            # NixOS modules
└── flake.nix           # Nix flake

Go Backend Architecture

The backend provides all system integration through these key components:

1. IPC Server (`internal/server/`)

JSON-based RPC over Unix socket (/tmp/dms-ipc-<uid>.sock) with 15+ submodules:

apppicker/ - Application search and launch
bluez/ - Bluetooth device management
brightness/ - Display and monitor brightness
browser/ - Web browser integration
clipboard/ - Clipboard history and persistence
cups/ - Printer management
dbus/ - Generic D-Bus interface access
dwl/ - dwl/MangoWC compositor integration
evdev/ - Keyboard input device monitoring
extworkspace/ - Workspace protocol integration
freedesktop/ - Desktop portal integration
loginctl/ - systemd-logind (power, sessions, inhibitors)
network/ - Network management (multi-backend)
params/ - IPC parameter validation
plugins/ - Plugin lifecycle management
thememode/ - Dark/light mode synchronization
themes/ - Theme registry operations
wayland/ - Night mode, gamma control, output management
wlcontext/ - Wayland connection management
wlroutput/ - wlr-output-management protocol

2. CLI Commands (`cmd/dms/`)

The dms CLI provides 20+ commands:

dms run [-d]                    # Start shell (daemon mode)
dms restart / kill              # Manage shell process
dms ipc <command> [args]        # Send IPC commands
dms brightness [list|set]       # Display brightness control
dms color pick [--rgb|--hsv]    # Native color picker
dms clipboard [list|clear]      # Clipboard management
dms screenshot [area|output]    # Take screenshots
dms notify send <msg>           # Send notifications
dms dpms [on|off]              # Display power management
dms keybinds [reload|list]     # Keybind management
dms windowrules [add|remove]   # Window rules management
dms matugen [generate|reload]  # Theme generation
dms dank16 [generate]          # Terminal theme generation
dms config [get|set]           # Configuration management
dms features                    # Show available features
dms doctor                      # System diagnostics
dms plugins [browse|install]   # Plugin management
dms update [check]             # Update DMS and deps
dms greeter [install|enable]   # Greeter management

3. Wayland Integration (`internal/wayland/`, `internal/proto/`)

Native Wayland protocol implementations (as client):

wlr-gamma-control-unstable-v1 - Night mode color temperature
wlr-screencopy-unstable-v1 - Screenshots and color picker
wlr-layer-shell-unstable-v1 - Overlay surfaces
wlr-output-management-unstable-v1 - Display configuration
wlr-output-power-management-unstable-v1 - DPMS control
ext-data-control-v1 - Clipboard history
ext-workspace-v1 - Workspace integration
dwl-ipc-unstable-v2 - dwl/MangoWC IPC
keyboard-shortcuts-inhibit-unstable-v1 - Shortcut inhibition
wp-viewporter - Fractional scaling support

4. D-Bus Integration (`internal/server/bluez/`, `internal/server/network/`, etc.)

Client interfaces (consuming external services):

org.bluez - Bluetooth with pairing agent
org.freedesktop.NetworkManager - Network management
net.connman.iwd - iwd Wi-Fi backend
org.freedesktop.network1 - systemd-networkd
org.freedesktop.login1 - Session control, inhibitors, brightness
org.freedesktop.Accounts - User account info
org.freedesktop.portal.Desktop - Desktop appearance settings
CUPS via IPP - Printer management

Server interfaces (implementing services):

org.freedesktop.ScreenSaver - Screensaver inhibition for media playback

5. Distribution Support (`internal/distros/`)

dankinstall TUI installer with full support for:

Arch Linux - pacman + AUR (yay/paru)
Fedora - dnf + COPR
Debian - apt + OBS repos
Ubuntu - apt + PPAs
openSUSE - zypper + OBS
Gentoo - emerge + GURU overlay + USE flags

Each distro has custom package mappings, dependency detection, and installation logic.

QML Frontend Architecture

The frontend follows a clean modular architecture with shell.qml reduced to ~250 lines:

shell.qml           # Main entry point (minimal orchestration)
├── Common/         # Shared resources (12 files)
│   ├── Theme.qml   # Material Design 3 theme singleton
│   ├── SettingsData.qml # User preferences and configuration
│   ├── SessionData.qml # Session state management
│   ├── Colors.qml  # Dynamic color scheme
│   └── [8 more utility files]
├── Services/       # System integration singletons (20 files)
│   ├── AudioService.qml
│   ├── NetworkService.qml
│   ├── BluetoothService.qml
│   ├── DisplayService.qml
│   ├── NotificationService.qml
│   ├── WeatherService.qml
│   ├── PluginService.qml
│   └── [14 more services]
├── Modules/        # UI components (93 files)
│   ├── TopBar/     # Panel components (13 files)
│   ├── ControlCenter/ # System controls (13 files)
│   ├── Notifications/ # Notification system (12 files)
│   ├── AppDrawer/  # Application launcher (3 files)
│   ├── Settings/   # Configuration interface (11 files)
│   ├── ProcessList/ # System monitoring (8 files)
│   ├── Dock/       # Application dock (6 files)
│   ├── Lock/       # Screen lock system (4 files)
│   └── [23 more module files]
├── Modals/         # Full-screen overlays (10 files)
│   ├── SettingsModal.qml
│   ├── ClipboardHistoryModal.qml
│   ├── ProcessListModal.qml
│   ├── PluginSettingsModal.qml
│   └── [7 more modals]
├── Widgets/        # Reusable UI controls (19 files)
│   ├── DankIcon.qml
│   ├── DankSlider.qml
│   ├── DankToggle.qml
│   ├── DankTabBar.qml
│   ├── DankGridView.qml
│   ├── DankListView.qml
│   └── [13 more widgets]
└── plugins/        # External plugins directory ($CONFIGPATH/DankMaterialShell/plugins/)
    └── PluginName/ # Example Plugin structure
        ├── plugin.json            # Plugin manifest
        ├── PluginNameWidget.qml   # Widget component
        └── PluginNameSettings.qml # Settings UI

Component Organization

Shell Entry Point (shell.qml)
- Minimal orchestration layer (~250 lines)
- Imports and instantiates components
- Handles global state and property bindings
- Multi-monitor support using Quickshell's Variants
Common/ - Shared resources
- Theme.qml - Material Design 3 theme singleton with consistent colors, spacing, fonts
- Utilities.js - Shared functions for workspace parsing, notifications, menu handling
Services/ - IPC client wrappers (20 singletons)
- Pattern: All services use Singleton type with id: root
- Architecture: Thin QML wrappers that communicate with Go backend via IPC
- Examples: AudioService, NetworkService, BluetoothService, DisplayService, WeatherService, NotificationService, CalendarService, BatteryService, NiriService, MprisController
- Services expose properties and functions that send IPC requests to the Go backend
- The Go backend handles all actual system integration (D-Bus, Wayland, hardware control)
- QML services receive IPC responses and update their properties for reactive UI binding
Modules/ - UI components (93 files)
- TopBar/: Panel components with workspace switching, system indicators, media controls
- ControlCenter/: System controls for WiFi, Bluetooth, audio, display settings
- Notifications/: Complete notification system with center, popups, and keyboard navigation
- AppDrawer/: Application launcher with grid/list views and category filtering
- Settings/: Comprehensive configuration interface with multiple tabs
- ProcessList/: System monitoring with process management and performance metrics
- Dock/: Application dock with running apps and window management
- Lock/: Screen lock system with authentication
Modals/ - Full-screen overlays (10 files)
- Modal system for settings, clipboard history, file browser, network info, power menu
- Unified modal management with consistent styling and keyboard navigation
Widgets/ - Reusable UI controls (19 files)
- DankIcon: Centralized icon component with Material Design font integration
- DankSlider: Enhanced slider with animations and smart detection
- DankToggle: Consistent toggle switch component
- DankTabBar: Unified tab bar implementation
- DankGridView: Reusable grid view with adaptive columns
- DankListView: Reusable list view with configurable styling
- DankTextField: Styled text input with validation
- DankDropdown: Dropdown selection component
- DankPopout: Base popout component for overlays
- StateLayer: Material Design 3 interaction states
- StyledRect/StyledText: Themed base components
- CachingImage: Optimized image loading with caching
- DankLocationSearch: Location picker with search
- SystemLogo: Animated system branding component
Plugins/ - External plugin system ($CONFIGPATH/DankMaterialShell/plugins/)
- PluginService: Discovers, loads, and manages plugin lifecycle
- Dynamic Loading: Plugins loaded at runtime from external directory
- DankBar Integration: Plugin widgets rendered alongside built-in widgets
- Settings System: Per-plugin settings with persistence

Key Architectural Patterns

Singleton Services Pattern:

import QtQuick
import Quickshell
import Quickshell.Io
pragma Singleton
pragma ComponentBehavior: Bound

Singleton {
    id: root

    property type value: defaultValue

    function performAction() { /* implementation */ }
}

Smart Feature Detection: Services detect system capabilities:

property bool featureAvailable: false
// Auto-hide UI elements when features unavailable
visible: ServiceName.featureAvailable

Property Bindings: Reactive UI updates through property binding
Material Design Theming: Consistent use of Theme singleton throughout

Important Components

ControlCenter: System controls (WiFi, Bluetooth, brightness, volume, night mode)
AppLauncher: Full-featured app grid/list with 93+ applications, search, categories
ClipboardHistoryModal: Complete clipboard management with cliphist integration
TopBar: Per-monitor panels with workspace switching, clock, system tray
System App Theming: Automatic GTK and Qt application theming using matugen templates

Key Widgets

DankIcon: Centralized icon component with automatic Material Design font detection
DankSlider: Enhanced slider with animations and smart detection
DankToggle: Consistent toggle switch component
DankTabBar: Unified tab bar implementation
DankGridView: Reusable grid view with adaptive columns
DankListView: Reusable list view with configurable styling

Code Conventions

Internationalization (I18n)

When adding user-facing strings, wrap them in I18n.tr() with context:

import qs.Common

Text {
    text: I18n.tr("Hello World", "Hello world greeting that appears on the lock screen")
}

Best practices:

Keep new terms to a minimum - reuse existing translations when possible
Check quickshell/translations/en.json for existing terms
Example: Use "Autoconnect" instead of "Auto-connect" if it's already translated
Provide clear context for translators in the second parameter

QML Style Guidelines

Structure and Formatting:
- Use 4-space indentation
- id should be the first property
- Properties before signal handlers before child components
- Prefer property bindings over imperative code
- CRITICAL: NEVER add comments unless absolutely essential for complex logic understanding. Code should be self-documenting through clear naming and structure. Comments are a code smell indicating unclear implementation.
- Use guard statements, example if (abc) { something() return;} somethingElse();
- Don't use crazy ternary stuff, but use it for simple if else only. propertyVal: a ? b : c
Naming Conventions:
- Services: Use Singleton type with id: root
- Components: Use descriptive names (e.g., DankSlider, TopBar)
- Properties: camelCase for properties, PascalCase for types
Null-Safe Operations:
- Use object?.property

Component Structure:

// For regular components
Item {
    id: root

    property type name: value

    signal customSignal(type param)

    onSignal: { /* handler */ }

    Component { /* children */ }
}

// For services (singletons)
Singleton {
    id: root

    property bool featureAvailable: false
    property type currentValue: defaultValue

    function performAction(param) { /* implementation */ }
}

Import Guidelines

QML Import Order

import QtQuick
import QtQuick.Controls  // If needed
import Quickshell
import Quickshell.Widgets
import Quickshell.Io     // For Process, FileView
import qs.Common         // For Theme, utilities
import qs.Services       // For service access
import qs.Widgets        // For reusable widgets (DankIcon, etc.)

Go Import Order

Follow standard Go conventions:

import (
    // Standard library
    "context"
    "fmt"
    "os"

    // External dependencies
    "github.com/godbus/dbus/v5"
    "github.com/spf13/cobra"

    // Internal packages
    "github.com/AvengeMedia/DankMaterialShell/core/internal/server/models"
    "github.com/AvengeMedia/DankMaterialShell/core/internal/utils"
)

Service Dependencies:

QML Services should NOT import other QML services
Modules and Widgets can import and use services via property bindings
Use Theme.propertyName for consistent styling
Use DankIcon { name: "icon_name" } for all icons instead of manual Text components

Go Backend Code Conventions

1. Package Structure

cmd/ - Binary entrypoints only, minimal logic
internal/ - Implementation packages (not importable by external projects)
pkg/ - Shared packages (potentially importable)
Each package should have a clear, single responsibility

2. Error Handling

// Always wrap errors with context
if err != nil {
    return fmt.Errorf("failed to connect to D-Bus: %w", err)
}

// Use custom error types for specific error handling
if errors.Is(err, errdefs.ErrNotFound) {
    // Handle specific error
}

3. IPC Handler Pattern

All server modules should follow this pattern:

package mymodule

import (
    "github.com/AvengeMedia/DankMaterialShell/core/internal/server/models"
    "github.com/AvengeMedia/DankMaterialShell/core/internal/server/params"
)

type Manager struct {
    // State, connections, etc.
}

func NewManager() (*Manager, error) {
    // Initialize
    return &Manager{}, nil
}

func (m *Manager) HandleRequest(req models.Request) models.Response {
    switch req.Method {
    case "list":
        return m.handleList(req)
    case "action":
        return m.handleAction(req)
    default:
        return models.ErrorResponse(req.ID, "unknown method")
    }
}

func (m *Manager) handleAction(req models.Request) models.Response {
    // Extract and validate parameters
    param, err := params.String(req.Params, "name")
    if err != nil {
        return models.ErrorResponse(req.ID, err.Error())
    }

    // Perform action
    result, err := m.doSomething(param)
    if err != nil {
        return models.ErrorResponse(req.ID, err.Error())
    }

    return models.SuccessResponse(req.ID, result)
}

4. D-Bus Integration

// Use context for cancellation
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// Always check for D-Bus availability
if !dbusutil.ServiceExists(conn, "org.bluez") {
    return fmt.Errorf("bluetooth service not available")
}

// Handle signals properly with channels
signals := make(chan *dbus.Signal, 10)
conn.Signal(signals)
defer conn.RemoveSignal(signals)

5. Wayland Protocol Integration

// Check protocol availability before use
if registry.GetGammaControl() == nil {
    return errdefs.ErrNotSupported
}

// Clean up Wayland resources
defer output.Destroy()
defer surface.Destroy()

6. Testing

// Use table-driven tests
func TestManager_HandleRequest(t *testing.T) {
    tests := []struct {
        name    string
        request models.Request
        want    models.Response
        wantErr bool
    }{
        {
            name: "valid request",
            request: models.Request{
                ID:     "1",
                Method: "list",
            },
            wantErr: false,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            m := NewManager()
            got := m.HandleRequest(tt.request)
            // Assertions
        })
    }
}

// Use mocks for external dependencies (see internal/mocks/)

7. Logging

import "github.com/AvengeMedia/DankMaterialShell/core/internal/log"

// Use appropriate log levels
log.Debug("Processing request", "method", req.Method)
log.Info("Service started", "address", addr)
log.Warn("Feature unavailable", "reason", "missing dependency")
log.Error("Failed to connect", "error", err)
log.Fatal("Critical failure", "error", err) // Only for unrecoverable errors

Component Development Patterns

QML Frontend Patterns

Code Reuse - Search Before Writing:
- ALWAYS search the codebase for existing functions before writing new ones
- Use Grep or Glob tools to find existing implementations (e.g., search for "getWifiIcon", "getDeviceIcon")
- Many utility functions already exist in Services/ and Common/ - reuse them instead of duplicating
- Examples of existing utility functions: Theme.getBatteryIcon(), BluetoothService.getDeviceIcon(), WeatherService.getWeatherIcon()
- If similar functionality exists, extend or refactor rather than duplicate

Smart Feature Detection:

// In services - detect capabilities
property bool brightnessAvailable: false

// In modules - adapt UI accordingly
DankSlider {
    visible: DisplayService.brightnessAvailable
    enabled: DisplayService.brightnessAvailable
    value: DisplayService.brightnessLevel
}

Reusable Components:
- Create reusable widgets for common patterns (like DankSlider)
- Use configurable properties for different use cases
- Include proper signal handling with unique names (avoid valueChanged)
Service Integration:
- Services expose properties and functions
- Modules and Widgets bind to service properties for reactive updates
- Use service functions for actions: ServiceName.performAction(value)
- CRITICAL: DO NOT create wrapper functions for everything - bind directly to underlying APIs when possible
- Example: Use BluetoothService.adapter.discovering = true instead of BluetoothService.startScan()
- Example: Use device.connect() directly instead of BluetoothService.connect(device.address)

Error Handling and Debugging

Console Logging:

// Use appropriate log levels
console.log("Info message")           // General info
console.warn("Warning message")       // Warnings
console.error("Error message")        // Errors

// Include context in service operations
onExited: (exitCode) => {
    if (exitCode !== 0) {
        console.warn("Service failed:", serviceName, "exit code:", exitCode)
    }
}

Graceful Degradation:
- Always check feature availability before showing UI
- Provide fallbacks for missing system tools
- Use visible and enabled properties appropriately

Multi-Monitor Support

The shell uses Quickshell's Variants pattern for multi-monitor support:

Each connected monitor gets its own top bar instance
Workspace switchers are compositor-aware (6 compositors supported)
Monitors are automatically detected by screen name (DP-1, DP-2, etc.)
Niri: Workspaces dynamically synchronized with per-output workspaces
Hyprland: Integrates with Hyprland's workspace system
MangoWC: Uses dwl-ipc-unstable-v2 for tag management
Sway/labwc/Scroll: Standard i3 IPC integration

IPC Communication Model

QML ↔ Go Backend Communication

The shell uses a Unix socket-based IPC system for all system integration:

Go Backend (core/internal/server/) runs an IPC server on /tmp/dms-ipc-<uid>.sock
QML Services send JSON-RPC requests to the backend
Backend handles system integration (D-Bus, Wayland, hardware) and responds
QML Services receive responses and update properties for UI reactivity

Example Flow:

User clicks WiFi network in UI
  ↓
QML NetworkService.connectNetwork(ssid, password)
  ↓
IPC Request: {"method": "network.connect", "params": {...}}
  ↓
Go Backend: internal/server/network/ handles D-Bus to NetworkManager
  ↓
IPC Response: {"result": {"success": true}}
  ↓
QML Service updates properties → UI updates reactively

Why this architecture?

Separation of concerns: UI (QML) vs system integration (Go)
Type safety: Go provides compile-time safety for system APIs
Performance: Go handles expensive operations without blocking UI
Robustness: Backend crashes don't crash the UI, and vice versa
Testing: Backend can be tested independently of UI

Development implications:

QML Services should be thin wrappers - minimal logic, just IPC calls
System integration logic belongs in Go backend packages
When adding features, implement backend first, then QML wrapper
Use dms ipc <command> CLI to test backend functionality independently

Common Development Tasks

Testing and Validation

When modifying the shell:

QML Frontend:

Test changes: qs -p . (automatic reload on file changes)
Code quality: Run ./qmlformat-all.sh or qmlformat -i **/*.qml and qmllint **/*.qml
Performance: Ensure animations remain smooth (60 FPS target)
Theming: Use Theme.propertyName for Material Design 3 consistency

Go Backend:

Build: cd core && make to build dms CLI
Tests: make test to run Go unit tests (add appropriate test coverage for new code)
Linting: gofmt -w ., go mod tidy, and golangci-lint run
IPC testing: Use dms ipc <command> to test backend functionality
Rebuild: After backend changes, rebuild with make and restart shell

Integration:

Full test: dms restart to restart both backend and frontend
Wayland compatibility: Test on Wayland session
Multi-monitor: Verify behavior with multiple displays
Compositor compatibility: Test on Niri, Hyprland, MangoWC, Sway, labwc, Scroll when possible
Distribution compatibility: Test installation on Arch, Fedora, Debian, Ubuntu, openSUSE, Gentoo
Feature detection: Test on systems with/without required tools

Adding New Modules

Create component:

# Create new module file
touch Modules/NewModule.qml

Follow module patterns:
- Use Theme.propertyName for styling
- Import qs.Common and qs.Services as needed
- Import qs.Widgets for reusable components
- Bind to service properties for reactive updates
- Consider per-screen vs global behavior
- Use DankIcon for icons instead of manual Text components

Integration in shell.qml:

NewModule {
    id: newModule
    // Configure properties
}

Adding New Widgets

Create component:

# Create new widget file
touch Widgets/NewWidget.qml

Follow widget patterns:
- Use Theme.propertyName for styling
- Import qs.Common for theming
- Focus on reusability and composition
- Keep widgets simple and focused
- Use DankIcon for icons instead of manual Text components

Adding New Services

Important: Most system integration should be done in the Go backend, with QML services as thin IPC wrappers.

Step 1: Implement Go Backend

Create backend package:

mkdir -p core/internal/server/newsystem

Implement backend logic (core/internal/server/newsystem/manager.go):

package newsystem

import (
    "github.com/AvengeMedia/DankMaterialShell/core/internal/server/models"
)

type Manager struct {
    // State and D-Bus connections
}

func NewManager() (*Manager, error) {
    // Initialize D-Bus connections, Wayland protocols, etc.
    return &Manager{}, nil
}

func (m *Manager) HandleRequest(req models.Request) models.Response {
    // Handle IPC requests
}

Add IPC handler in core/internal/server/router.go:

newsystemMgr, _ := newsystem.NewManager()
router["newsystem"] = newsystemMgr.HandleRequest

Test backend: dms ipc newsystem.action '{"param": "value"}'

Step 2: Create QML Wrapper

Create service:

// Services/NewService.qml
import QtQuick
import Quickshell
import Quickshell.Io
pragma Singleton
pragma ComponentBehavior: Bound

Singleton {
    id: root

    property bool featureAvailable: false
    property type currentValue: defaultValue

    function performAction(param) {
        // Send IPC request to Go backend
        ipcClient.send("newsystem.action", {param: param})
    }

    // Handle IPC responses to update properties
    Connections {
        target: IPCClient
        function onResponse(method, data) {
            if (method === "newsystem.status") {
                currentValue = data.value
            }
        }
    }
}

Use in modules:

property alias serviceValue: NewService.currentValue

SomeControl {
    visible: NewService.featureAvailable
    enabled: NewService.featureAvailable
    onTriggered: NewService.performAction(value)
}

Creating Plugins

Plugins are external, dynamically-loaded components that extend DankMaterialShell functionality. Plugins are stored in ~/.config/DankMaterialShell/plugins/ and have their settings isolated from core DMS settings.

Plugin Types:

Widget plugins ("type": "widget" or omit type field): Display UI components in DankBar
Daemon plugins ("type": "daemon"): Run invisibly in the background without UI

Create plugin directory:

mkdir -p ~/.config/DankMaterialShell/plugins/YourPlugin

Create manifest (plugin.json):

{
    "id": "yourPlugin",
    "name": "Your Plugin",
    "description": "Widget description",
    "version": "1.0.0",
    "author": "Your Name",
    "icon": "extension",
    "type": "widget",
    "component": "./YourWidget.qml",
    "settings": "./YourSettings.qml",
    "permissions": ["settings_read", "settings_write"]
}

Create widget component (YourWidget.qml):

import QtQuick
import qs.Services

Rectangle {
    id: root

    property bool compactMode: false
    property string section: "center"
    property real widgetHeight: 30
    property var pluginService: null

    width: content.implicitWidth + 16
    height: widgetHeight
    radius: 8
    color: "#20FFFFFF"

    Component.onCompleted: {
        if (pluginService) {
            var data = pluginService.loadPluginData("yourPlugin", "key", defaultValue)
        }
    }
}

Create settings component (YourSettings.qml):

import QtQuick
import QtQuick.Controls

FocusScope {
    id: root

    property var pluginService: null

    implicitHeight: settingsColumn.implicitHeight
    height: implicitHeight

    Column {
        id: settingsColumn
        anchors.fill: parent
        anchors.margins: 16
        spacing: 12

        Text {
            text: "Your Plugin Settings"
            font.pixelSize: 18
            font.weight: Font.Bold
        }

        // Your settings UI here
    }

    function saveSettings(key, value) {
        if (pluginService) {
            pluginService.savePluginData("yourPlugin", key, value)
        }
    }

    function loadSettings(key, defaultValue) {
        if (pluginService) {
            return pluginService.loadPluginData("yourPlugin", key, defaultValue)
        }
        return defaultValue
    }
}

Enable plugin:
- Open Settings → Plugins
- Click "Scan for Plugins"
- Toggle plugin to enable
- Add plugin ID to DankBar widget list

Daemon Plugins

Daemon plugins run invisibly in the background without any UI components. They're useful for monitoring system events, background tasks, or data synchronization.