Merge pull request #4 from derryl/claude-init

Add CLAUDE.md and streamline README for end users

Author: derryl

CLAUDE.md

@@ -0,0 +1,59 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+A development environment for building and customizing SDDM login themes for KDE Plasma 6. Themes are written in pure QtQuick/QML (no KDE Plasma library dependencies) and can be previewed in a standalone window without restarting SDDM.
+
+## Commands
+
+### Live preview (primary development loop)
+```sh
+./scripts/preview.sh                  # preview the default theme
+./scripts/preview.sh -theme <name>    # preview a specific theme
+qml6 preview/Preview.qml             # one-shot preview (no file watching)
+```
+
+### Lint (static analysis + runtime type check)
+```sh
+./scripts/lint-qml.sh                 # lint all themes
+./scripts/lint-qml.sh -theme <name>   # lint a specific theme
+```
+CI runs this on every push/PR. It runs `qmllint` for static analysis, then launches the preview under `xvfb` for 3 seconds to catch runtime type errors (`Unable to assign`, `ReferenceError`, `TypeError`).
+
+### Full-fidelity SDDM test
+```sh
+./scripts/test-sddm.sh                # test default theme with real SDDM greeter
+./scripts/test-sddm.sh -theme <name>
+```
+
+## Architecture
+
+### Theme structure
+Themes live under `themes/<name>/`. The default theme is at `themes/default/`.
+
+Each theme contains:
+- `Main.qml` — SDDM entry point; root `Item` that uses SDDM-injected context properties
+- `theme.conf` — all configurable values (colors, fonts, background, clock format, screen dimensions)
+- `metadata.desktop` — SDDM theme registration metadata
+- `components/` — UI components (Clock, LoginForm, SessionSelector, PowerBar)
+- `assets/` — background image and other static assets
+
+### Preview harness
+`preview/Preview.qml` mirrors `Main.qml` layout but replaces SDDM context properties with mock objects (`mockSddm`, `mockConfig`, `mockUserModel`, `mockSessionModel`, `mockKeyboard`). The preview script symlinks the selected theme's `components/` and `assets/` into `preview/` so relative QML imports resolve correctly.
+
+In preview mode, use password `test` for successful login; any other password triggers "Login Failed".
+
+### SDDM context properties
+SDDM injects five globals that themes depend on: `sddm`, `config`, `userModel`, `sessionModel`, `keyboard`. Components receive these as explicit properties rather than accessing globals directly, making them portable between Main.qml (real SDDM) and Preview.qml (mocks).
+
+### QML style
+All scripts set `QT_QUICK_CONTROLS_STYLE=Basic` to avoid Breeze/Plasma-specific errors outside a full Plasma session.
+
+## Key Conventions
+
+- Pure QtQuick only — no `org.kde.plasma.*`, `org.kde.breeze.components`, or `Kirigami` imports
+- Components take dependencies as explicit props (not SDDM context property access)
+- `qmllint` warnings about unresolved SDDM globals are expected and tolerated; only actual errors fail CI
+- All config values come through `theme.conf` and are accessed via `config.<key>` in QML

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Derryl Carter
+
+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.

README.md

@@ -6,99 +6,57 @@ Build and customize your KDE login screen without having to actually reinstall t
 
 This project gives you a live-preview development environment for SDDM themes on KDE Plasma 6. Edit QML, tweak colors, swap backgrounds -- and see every change instantly in a standalone window. When you're happy with the result, install it as your real login screen with one command.
 
-**Who is this for?** Anyone who wants to customize their KDE/SDDM login screen -- whether you're importing an existing theme to tweak it, or building one from scratch.
-
-## What's Inside
-
-```
-kde-lockscreen-builder/
-├── Main.qml                  # SDDM entry point (the actual theme)
-├── metadata.desktop           # Theme registration (Theme-API 2.0, Qt6)
-├── theme.conf                 # All configurable values: colors, fonts, background, clock
-├── components/
-│   ├── Clock.qml              # Date/time display
-│   ├── LoginForm.qml          # Username + password fields, login button
-│   ├── SessionSelector.qml    # Desktop session dropdown
-│   └── PowerBar.qml           # Suspend / reboot / shutdown buttons
-├── preview/
-│   └── Preview.qml            # Mock harness — previews your theme without SDDM
-├── scripts/
-│   ├── preview.sh             # File-watcher: auto-restarts preview on every save
-│   └── test-sddm.sh           # Full-fidelity SDDM greeter test
-├── assets/
-│   └── background.jpg         # Your background image
-└── faces/
-    └── .face.icon             # Default user avatar placeholder
-```
+## Quick Start
 
-## Prerequisites
+### Prerequisites
 
 - KDE Plasma 6 with SDDM
 - Qt 6 (`qt6-declarative` package -- provides `qml6`)
 - `entr` for file-watching (`sudo pacman -S entr` on Arch)
 
-## Quick Start
+### Start from the included starter theme
 
-### Option A: Start From the Included Starter Theme
-
-The repo ships with a minimal, clean theme that works out of the box. Clone and preview it immediately:
+The repo ships with a minimal, clean theme that works out of the box:
 
 ```sh
 git clone https://github.com/derryl/kde-lockscreen-builder.git
 cd kde-lockscreen-builder
-cp /path/to/your/wallpaper.jpg assets/background.jpg
+cp /path/to/your/wallpaper.jpg themes/default/assets/background.jpg
 ./scripts/preview.sh
 ```
 
 Edit any `.qml` file or `theme.conf`, save, and the preview window restarts automatically.
 
-### Option B: Import an Existing Theme
-
-Already have a theme you want to modify? Copy its files into this project to get the live-preview workflow:
-
-1. Clone this repo:
-
-   ```sh
-   git clone https://github.com/derryl/kde-lockscreen-builder.git
-   cd kde-lockscreen-builder
-   ```
-
-2. Copy the theme's files over the project files. SDDM themes typically have a `Main.qml`, `metadata.desktop`, `theme.conf`, and asset directories -- replace the ones in this repo with yours:
+### Or import an existing theme
 
-   ```sh
-   # Example: importing from an installed SDDM theme
-   cp -r /usr/share/sddm/themes/some-theme/* .
-   ```
+Already have a theme you want to modify? You can find community themes on the [KDE Store](https://store.kde.org/browse?cat=101&ord=rating), or copy one that's already installed on your system:
 
-3. Launch the preview:
-
-   ```sh
-   ./scripts/preview.sh
-   ```
+```sh
+# Example: importing from an installed SDDM theme
+cp -r /usr/share/sddm/themes/some-theme/* themes/default/
+./scripts/preview.sh
+```
 
-   If the imported theme uses KDE/Plasma-specific QML imports (e.g. `org.kde.plasma.*`), the standalone preview won't be able to render those parts. You can still use `./scripts/test-sddm.sh` for full-fidelity testing, or incrementally replace those imports with pure QtQuick equivalents.
+If the imported theme uses KDE/Plasma-specific QML imports (e.g. `org.kde.plasma.*`), the standalone preview won't render those parts. You can still use `./scripts/test-sddm.sh` for full-fidelity testing, or incrementally replace those imports with pure QtQuick equivalents.
 
 ## Development Workflow
 
-### Live Preview (primary loop)
-
-`preview/Preview.qml` mocks all SDDM-provided objects (`sddm`, `userModel`, `sessionModel`, `config`, `keyboard`) so your theme renders in a standalone window -- no real SDDM greeter needed.
+### Live preview
 
 ```sh
-./scripts/preview.sh
+./scripts/preview.sh                  # preview the default theme
+./scripts/preview.sh -theme <name>    # preview a specific theme under themes/
 ```
 
-This watches all `.qml`, `.conf`, and image files using `entr`. On every save, the preview window is killed and relaunched automatically.
+This watches all `.qml`, `.conf`, and image files. On every save, the preview window restarts automatically. In preview mode, type the password `test` to simulate a successful login.
 
 You can also launch the preview once without file-watching:
 
 ```sh
 qml6 preview/Preview.qml
 ```
 
-In preview mode, type the password `test` to simulate a successful login. Any other password triggers the "Login Failed" notification.
-
-### Full-Fidelity SDDM Test
+### Full-fidelity SDDM test
 
 Periodically verify your theme against the real SDDM greeter:
 
@@ -140,7 +98,7 @@ Changes to `theme.conf` are picked up by the file watcher just like QML changes.
 
 ## Installing Your Theme
 
-When you're satisfied with your theme, install it so SDDM uses it at your real login screen. SDDM themes live in `/usr/share/sddm/themes/`.
+SDDM themes live in `/usr/share/sddm/themes/`.
 
 ### 1. Choose a theme name
 
@@ -155,19 +113,17 @@ Theme-Id=my-login-theme
 **Symlink (recommended during development)** -- lets you keep editing and see changes on next login:
 
 ```sh
-sudo ln -sf "$(pwd)" /usr/share/sddm/themes/my-login-theme
+sudo ln -sf "$(pwd)/themes/default" /usr/share/sddm/themes/my-login-theme
 ```
 
 **Copy (for a final install):**
 
 ```sh
-sudo cp -r . /usr/share/sddm/themes/my-login-theme
+sudo cp -r themes/default /usr/share/sddm/themes/my-login-theme
 ```
 
 ### 3. Activate the theme
 
-Tell SDDM to use your theme:
-
 ```sh
 sudo mkdir -p /etc/sddm.conf.d
 sudo tee /etc/sddm.conf.d/theme.conf > /dev/null <<EOF
@@ -180,21 +136,16 @@ Or use the GUI: **System Settings > Colors & Themes > Login Screen (SDDM)**.
 
 ### 4. Verify
 
-Run the full-fidelity test against the installed path to confirm everything works:
-
 ```sh
 sddm-greeter-qt6 --test-mode --theme /usr/share/sddm/themes/my-login-theme
 ```
 
-## Architecture Notes
-
-The included starter theme is built with **pure QtQuick** -- no imports from `org.kde.plasma.*`, `org.kde.breeze.components`, or `Kirigami`. This means:
-
-- Total control over every visual element
-- No dependency on KDE Plasma libraries at the SDDM level
-- Easy mocking: only 5 SDDM globals need stubs (`sddm`, `config`, `userModel`, `sessionModel`, `keyboard`)
+## Useful Links
 
-Components receive their dependencies as explicit properties rather than relying on SDDM context properties directly, making them testable in the preview harness and reusable across themes.
+- [SDDM Theming Guide](https://github.com/sddm/sddm/wiki/Theming) -- API reference for the SDDM context properties (`sddm`, `userModel`, `sessionModel`, etc.) and theme structure
+- [KDE Store: SDDM Login Themes](https://store.kde.org/browse?cat=101&ord=rating) -- community-made themes to use as starting points or inspiration
+- [Qt QML Documentation](https://doc.qt.io/qt-6/qtqml-index.html) -- language reference for QML
+- [Qt Quick Documentation](https://doc.qt.io/qt-6/qtquick-index.html) -- the UI framework used by SDDM themes
 
 ## License