docs: update readme

README.md

@@ -4,39 +4,51 @@
 
 ## ⚠️ WORK IN PROGRESS ⚠️
 
-Oh deer! 🦌 You've stumbled upon `layer-shika`, a rust library crate that provides a layer shell implementation for wayland compositors, using slint for the GUI. It allows you to create overlay windows and panels or bars that integrate seamlessly with wayland-based desktop environments.
+Oh deer! 🦌 You've stumbled upon `layer-shika`, a Rust library providing Wayland layer shell integration with Slint UI. Create overlay windows, status bars, panels, popups, and more, that integrate seamlessly with Wayland compositors.
 
 Please note that this library is currently in early development and is not yet ready for production use.
 
-## Current Status
+## Features
 
-- **Architecture**: Clean hexagonal architecture with domain, adapters, and composition layers
+- **Slint Integration**: Runtime `.slint` file compilation via slint-interpreter or compile-time code generation. Support via pre-compiled is planned.
-- **Rendering**: EGL context management with `femtovg` renderer integration
+- **Multi-Surface Support**: Create multiple independent layer shell windows, each with its own configuration and lifecycle
-- **Wayland**: Comprehensive layer shell protocol support using `smithay-client-toolkit`
+- **Flexible Configuration**: Both fluent builder API and declarative configuration support
-  - Output management and configuration
+- **Comprehensive Popup System**: Full xdg-popup protocol implementation with multiple positioning modes, grab support, and content-based sizing (rework in progress)
-  - Surface lifecycle management
+- **Multi-Output Support**: Per-monitor component instances with flexible output policies (primary only, all outputs, specific outputs)
-  - Basic xdg popup support
+- **Event Loop Integration**: Custom event sources (timers, channels, file descriptors) via calloop integration
-  - Event handling system
+- **Clean-like Architecture**: Organized as a Cargo workspace with clear separation of concerns (domain, adapters, composition)
-- **UI Integration**: Slint integration layer with custom rendering backend
+- **HiDPI Support**: Configurable scale factors for high-resolution displays
-- **Documentation**: Work in progress
+
-- **Examples**: Available - see [examples/](examples/) directory
+## Architecture
+
+layer-shika is organized as a **Cargo workspace** with three crates:
+
+- **domain** ([crates/domain/](crates/domain/)): Core domain models, value objects, and port trait definitions. No framework dependencies.
+- **adapters** ([crates/adapters/](crates/adapters/)): Concrete implementations for Wayland (smithay-client-toolkit), rendering (femtovg + EGL), and platform integration.
+- **composition** ([crates/composition/](crates/composition/)): Public API layer providing Shell-based API, builder patterns, and system integration.
+
+This clean-like architecture enables flexibility, and clear dependency boundaries (composition → adapters → domain).
+
+## Current Status
 
 **What's Working:**
 
-- EGL context creation and management
+- Multi-surface shell with builder and declarative configuration APIs
-- Wayland layer shell surface creation
+- Wayland layer shell protocol (wlr-layer-shell) via smithay-client-toolkit
-- XDG popup support (with some limitations: resizing needed)
+- Full xdg-popup protocol support with flexible positioning and sizing
-- Basic rendering with femtovg
+- EGL context management with femtovg renderer integration
-- Output detection and management
+- Multi-output detection, tracking, and per-output component instances
-- Event handling framework
+- Event handling framework with ShellEventContext and ShellControl
+- Custom event loop integration (timers, channels, file descriptors)
+- HiDPI scale factor support
 
 **Known Limitations:**
 
-- Not all features are fully implemented or tested
+- API may change before 1.0
-- API is still unstable and may change
+- Documentation is work in progress
-- Comprehensive documentation pending
+- Some edge cases may not be fully tested
 
-It's recommended to wait for a stable release before using this library in production projects. Development is trying to be as fast as a running skippy deer!
+It's recommended to wait for a stable release before using this library in production projects, but if you want you can experiment with the current version. Development is trying to be as fast as a running skippy deer!
 
 ## Quick Start
 
@@ -59,7 +71,7 @@ If you want to use it now, use this repo as dependency instead of crates.io outd
 
 ## First Stable Release
 
-It aim to have the first stable release by the end of 2025, with a focus on core functionality and API stability.
+The aim is to have the first stable release by the end of 2025, with a focus on core functionality and API stability.
 
 Stay tuned!