Merge branch 'v0.2.0' - Theme system, refactoring, and documentation

Major features and improvements:
- Theme system with onThemeEnable/onThemeDisable lifecycle hooks
- Style context for type-safe theme variables
- Context-driven layout slots (no more prop drilling)
- Refactored app structure into components and pages
- Full CSS variable support in all plugins
- Dark theme plugin implementation
- Comprehensive theme system documentation
- GitHub Pages documentation setup

Breaking changes:
- Layout slots now use context hooks instead of props
- RouterService.getRoutes() method added

Commits included:
- Theme persistence and style context
- Plugin updates for theme support
- Documentation updates
- App refactoring
- Context-based layout slots
- GitHub Pages setup

Author: binyamin555

.github/workflows/pages.yml

@@ -0,0 +1,57 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+    paths:
+      - 'docs/**'
+      - 'README.md'
+      - '.github/workflows/pages.yml'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+        
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./docs
+          destination: ./_site
+          
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,6 +1,6 @@
 # React PKL
 
-A **typesafe plugin system for React applications** written in TypeScript. React PKL allows you to extend React applications from external sources through a robust, type-safe plugin architecture.
+A **typesafe plugin system for React applications** written in TypeScript. React PKL allows you to extend React applications from external sources through a robust, type-safe plugin architecture with advanced theming support.
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue.svg)](https://www.typescriptlang.org/)
 [![React](https://img.shields.io/badge/React-18.0+-61dafb.svg)](https://reactjs.org/)
@@ -9,10 +9,13 @@ A **typesafe plugin system for React applications** written in TypeScript. React
 
 React PKL is designed for **SDK developers** who want to create extensible React applications. It provides the foundation for building plugin systems where:
 
-- Plugins can extend the UI through defined **slots**
+- Plugins can extend the UI through defined **slots** and **layout overrides**
 - Plugins receive a **typesafe context** from the host application
+- **Theme plugins** can override entire layout components with custom styling
+- **Static plugins** work without lifecycle management (perfect for themes)
 - Resources are **automatically cleaned up** when plugins are disabled
 - Plugins can be managed **locally** or fetched from a **remote source**
+- **Style context** provides type-safe access to theme variables
 
 ## 📦 Packages
 
@@ -292,6 +295,131 @@ Get all components registered for a slot:
 const toolbarComponents = useSlotComponents('toolbar');
 ```
 
+## 🎨 Theme System
+
+### Creating Theme Plugins
+
+Theme plugins use `onThemeEnable()` and `onThemeDisable()` to manage theme lifecycle:
+
+```typescript
+import { definePlugin, AppHeader, AppSidebar, StyleProvider } from 'my-sdk';
+
+const darkThemePlugin = definePlugin({
+  meta: {
+    id: 'com.example.dark-theme',
+    name: 'Dark Theme',
+    version: '1.0.0',
+  },
+  
+  // Theme plugins don't need activate/deactivate (static plugins)
+  // They only activate when set as the active theme
+  
+  onThemeEnable(slots) {
+    // Apply CSS variables
+    document.documentElement.style.setProperty('--bg-primary', '#1a1a1a');
+    document.documentElement.style.setProperty('--text-primary', '#e4e4e7');
+    
+    // Override layout slots with themed components
+    slots.set(AppHeader, DarkHeader);
+    slots.set(AppSidebar, DarkSidebar);
+    
+    // Return cleanup function
+    return () => {
+      document.documentElement.style.removeProperty('--bg-primary');
+      document.documentElement.style.removeProperty('--text-primary');
+    };
+  },
+  
+  onThemeDisable() {
+    console.log('Theme disabled - additional cleanup');
+  },
+});
+
+function DarkHeader({ toolbar }) {
+  return (
+    <StyleProvider variables={{
+      bgPrimary: '#1a1a1a',
+      textPrimary: '#e4e4e7',
+      accentColor: '#60a5fa',
+    }}>
+      <header style={{ background: 'linear-gradient(135deg, #18181b 0%, #27272a 100%)' }}>
+        {toolbar}
+      </header>
+    </StyleProvider>
+  );
+}
+```
+
+### Using StyleProvider
+
+Provide type-safe style variables to components:
+
+```tsx
+import { StyleProvider, useStyles } from 'my-sdk';
+
+function MyComponent() {
+  const styles = useStyles();
+  
+  return (
+    <div style={{
+      background: styles.bgPrimary,
+      color: styles.textPrimary,
+      borderColor: styles.borderColor,
+    }}>
+      Themed content
+    </div>
+  );
+}
+```
+
+### Setting Active Theme
+
+```typescript
+import { isThemePlugin } from '@react-pkl/core';
+
+// Check if a plugin is a theme plugin
+if (isThemePlugin(plugin)) {
+  pluginHost.setThemePlugin(plugin);
+}
+
+// Get current theme
+const currentTheme = pluginHost.getThemePlugin();
+
+// Remove theme (back to default)
+pluginHost.setThemePlugin(null);
+
+// Persist theme in localStorage
+localStorage.setItem('active-theme', plugin.meta.id);
+```
+
+### Static vs Dynamic Plugins
+
+React PKL supports two plugin types:
+
+```typescript
+import { isStaticPlugin, isThemePlugin } from '@react-pkl/core';
+
+// Static plugins - no activate/deactivate lifecycle
+// Perfect for theme plugins that only need theme lifecycle
+const themePlugin = {
+  meta: { id: 'theme', name: 'Theme', version: '1.0.0' },
+  onThemeEnable(slots) { /* ... */ },
+  onThemeDisable() { /* ... */ },
+};
+
+isStaticPlugin(themePlugin); // true
+isThemePlugin(themePlugin);  // true
+
+// Dynamic plugins - full lifecycle management
+const dataPlugin = {
+  meta: { id: 'data', name: 'Data', version: '1.0.0' },
+  async activate(context) { /* ... */ },
+  async deactivate() { /* ... */ },
+};
+
+isStaticPlugin(dataPlugin); // false
+```
+
 ## 🧩 Components
 
 ### `<PluginProvider>`
@@ -383,12 +511,22 @@ interface PluginModule<TContext> {
   // Optional lifecycle hooks
   activate?(context: TContext): void | Promise<void>;
   deactivate?(): void | Promise<void>;
+  
+  // Optional React entrypoint
+  entrypoint?(): ReactNode;
 
-  // Optional React components by slot name
-  components?: Record<string, ComponentType<any>>;
+  // Optional theme lifecycle hooks
+  onThemeEnable?(slots: Map<Function, Function>): void | (() => void);
+  onThemeDisable?(): void;
 }
 ```
 
+**Plugin Types:**
+- **Dynamic Plugins**: Have `activate`/`deactivate` - Full lifecycle management
+- **Static Plugins**: No `activate`/`deactivate` - Always available, perfect for themes
+- **Theme Plugins**: Have `onThemeEnable`/`onThemeDisable` - Can be set as active theme
+```
+
 ### TypeScript Plugin Helper
 
 Create a helper for better type inference:
@@ -469,8 +607,9 @@ The repository includes complete examples:
 - **`examples/plugins`** - Sample plugins demonstrating various features:
   - `hello-plugin` - Basic plugin with notification
   - `user-greeting-plugin` - Accesses app context
-  - `theme-toggle-plugin` - State management
+  - `theme-toggle-plugin` - State management with toolbar button
   - `custom-page-plugin` - Route registration with cleanup
+  - `dark-theme-plugin` - Complete theme with layout overrides and style context
 
 ## 🏛️ Design Philosophy
 

docs/README.md

@@ -0,0 +1,68 @@
+# React PKL Documentation
+
+This directory contains the comprehensive documentation for React PKL.
+
+## 📖 View Documentation
+
+**Online:** Visit [https://xpodev.github.io/react-pkl/](https://xpodev.github.io/react-pkl/)
+
+**Locally:** Browse the markdown files in this directory.
+
+## 📚 Available Documentation
+
+- **[index.md](./index.md)** - Documentation index and navigation
+- **[GETTING_STARTED.md](./GETTING_STARTED.md)** - Step-by-step guide for beginners
+- **[API.md](./API.md)** - Complete API reference
+- **[EXAMPLES.md](./EXAMPLES.md)** - Example walkthrough
+- **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)** - Quick reference guide
+- **[ADVANCED.md](./ADVANCED.md)** - Advanced usage patterns
+- **[THEME_SYSTEM.md](./THEME_SYSTEM.md)** - Theme system guide
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Architecture overview
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contribution guidelines
+
+## 🚀 Quick Start
+
+If you're new to React PKL:
+
+1. Read the [main README](../README.md) for project overview
+2. Follow the [Getting Started Guide](./GETTING_STARTED.md)
+3. Explore the [Examples](./EXAMPLES.md)
+
+## 🔧 GitHub Pages Setup
+
+This documentation is configured for GitHub Pages using Jekyll:
+
+- **Theme:** Cayman (defined in `_config.yml`)
+- **Configuration:** See `_config.yml` for settings
+- **Base URL:** `/react-pkl`
+
+### Local Preview
+
+To preview the documentation locally with Jekyll:
+
+```bash
+# Install Jekyll (if not already installed)
+gem install bundler jekyll
+
+# Serve the documentation
+cd docs
+jekyll serve
+```
+
+Then visit `http://localhost:4000/react-pkl/`
+
+## 📝 Contributing to Documentation
+
+When updating documentation:
+
+1. Follow markdown best practices
+2. Keep examples up-to-date with code
+3. Cross-reference related topics
+4. Test links work correctly
+5. Use clear, concise language
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.
+
+## 📄 License
+
+Same as the main project - see [../LICENSE](../LICENSE) if available.