refactor: Inicial structure for mobile and initial support for gsify (#52)

* refactor: prepare shell for mobile targets

Group modules by feature area instead of a flat modules tree. Add runtime target detection so desktop-only features can stay out of future mobile sessions.

Keep GJSify as an experimental separate build path with readable module output for review.

* feat(clipboard): enhance clipboard history functionality with sample actions and clear history option

feat(styles): update clipboard history styles for improved UI consistency

test(clipboard): add unit tests for clipboard log operations and positioning

test(ui): implement tests for clipboard panel layout and actions

fix(dash): handle potential errors in dash container positioning and actions

Author: leandromqrs

.gitignore

@@ -12,6 +12,8 @@ node_modules/
 
 # Build output
 dist/
+dist-gjsify/
+dist-gjsify-probe/
 
 # npm (legacy)
 package-lock.json
@@ -36,4 +38,8 @@ Thumbs.db
 .vagrant/
 .docs/
 docs/
-.superpowers/
+.superpowers/
+
+# IA Stuff
+.agents/
+skills-lock.json

AGENTS.md

@@ -64,16 +64,23 @@ Do not leave a task incomplete if either command reports errors or failures.
 
 - `src/` — TypeScript source root
   - `extension.ts` — entry point; iterates the registry and instantiates modules via each definition's `factory`
-  - `module.ts` — base `Module` class plus the shared `ModuleOption` / `ModuleMetadata` / `ModuleDefinition` types
+  - `module.ts` — base `Module` class plus the shared `ModuleOption` / `ModuleMetadata` / `ModuleDefinition` / runtime policy types
   - `registry.ts` — aggregator; imports each module's `definition` export and returns them in UI order (used by `extension.ts`)
   - `prefsMetadata.ts` — pure metadata mirror for the prefs UI; cannot import modules because prefs runs in `gnome-extensions-app` (no `resource:///org/gnome/shell/*` available). Also exports `getSections()` (the ordered list of prefs sections)
   - `prefs.ts` — generic extension preferences UI driven by `prefsMetadata.ts`; renders one `Adw.PreferencesGroup` per section
   - `core/` — Clean Architecture core
     - `context.ts` — `ExtensionContext` interface and implementation
     - `logger.ts` — Abstracted logging
     - `settings.ts` — `SettingsManager` abstraction for GSettings
-  - `modules/` — feature modules registered by `registry.ts`
-    - regular modules use one **folder** per feature module, named after the module (e.g., `dock/dock.ts`); the main entry file shares the folder name
+  - feature modules are grouped by semantic area instead of a single `modules/` root:
+    - `dock/` — dock module and dock-specific helpers
+    - `panel/` — GNOME panel and Quick Settings integrations
+    - `desktop/` — desktop-only modules such as tray icons
+    - `patches/` — focused Shell behavior patches and monkey-patches
+    - `theme/` — theme and color-scheme modules
+    - `privacy/` — privacy and screen-sharing behavior
+    - `clipboard/` — clipboard history module and UI
+  - `device/` — runtime target and hardware capability detection for future mobile work
   - `dev/` — developer-only tooling (e.g., `devTool.ts`), gated behind the `AURORA_DEVTOOLS=1` env var. **Not** a feature module: it is not in the registry, prefs, or gschema, and is instantiated directly by `extension.ts`
   - `shared/` — shared utilities used across modules (e.g., `quickSettings.ts`)
   - `styles/` — SCSS stylesheets (compiled to light + dark CSS)
@@ -97,13 +104,13 @@ Do not leave a task incomplete if either command reports errors or failures.
 
 1. **Settings via context:** Modules receive an `ExtensionContext` in their constructor and read configuration through `this.context.settings` (the `SettingsManager` abstraction) rather than touching `Gio.Settings` directly.
 2. **`Main` is fair game:** Importing `Main` (`resource:///org/gnome/shell/ui/main.js`) directly is the idiomatic GNOME-extension way and is expected — there is no shell adapter. Confidence in shell interactions comes from the `tests/shell/` integration suite running a real headless GNOME Shell, not from mocking `Main`.
-3. **Layering & testability:** Keep UI logic (Clutter/St) separated from pure domain logic. Extract complex algorithms into pure TypeScript files with no shell imports (e.g., `src/modules/dock/monitorTopology.ts`, `src/modules/trayIcons/trayState.ts`) so they can be unit-tested with `node --test`. UI/shell glue is covered by integration tests instead.
+3. **Layering & testability:** Keep UI logic (Clutter/St) separated from pure domain logic. Extract complex algorithms into pure TypeScript files with no shell imports (e.g., `src/dock/monitorTopology.ts`, `src/desktop/trayIcons/trayState.ts`) so they can be unit-tested with `node --test`. UI/shell glue is covered by integration tests instead.
 4. **Metadata-Driven UI:** The preferences window is generated dynamically from `src/prefsMetadata.ts` (a hand-maintained mirror of each module's metadata, kept in parity by `tests/unit/registry.test.ts`). If a module needs options, define them in the `options` array of its `ModuleDefinition` and mirror them into `prefsMetadata.ts`.
 5. **Self-Registering Modules:** Each module file exports a `definition: ModuleDefinition` co-located with its class. The factory that constructs the module lives on the definition itself — `src/registry.ts` is a pure aggregator and never references module classes directly.
 
 ## Adding a Module
 
-1. Create `src/modules/myModule/myModule.ts` with a `Module` subclass **and** a co-located `definition` export. Regular modules **must** live in their own folder named after the module (e.g., `dock/dock.ts`, `panel/panel.ts`).
+1. Create a module in the appropriate semantic area with a `Module` subclass **and** a co-located `definition` export. Single-file patches can live directly in `src/patches/`; complex modules should use a feature folder such as `src/panel/myModule/myModule.ts`.
 
 ```typescript
 import { gettext as _ } from 'gettext';
@@ -126,6 +133,7 @@ export const definition: ModuleDefinition = {
   section: 'behavior', // must match an id from getSections() in prefsMetadata.ts
   title: _('My Module'),
   subtitle: _('Description'),
+  runtime: { targets: ['desktop'] }, // optional; omitted modules default to desktop-only
   options: [
     { key: 'my-option', title: _('Option'), subtitle: _('Desc'), type: 'switch' },
   ],
@@ -136,7 +144,7 @@ export const definition: ModuleDefinition = {
 2. Register the definition in `src/registry.ts` (one import + one array entry, preserving UI order):
 
 ```typescript
-import { definition as myModule } from '~/modules/myModule/myModule.ts';
+import { definition as myModule } from '~/patches/myModule.ts';
 // …inside getModuleRegistry():
 return [/* …, */ myModule];
 ```

ARCHITECTURE.md

@@ -11,9 +11,10 @@ flowchart TD
   Shell[GNOME Shell] --> Extension[src/extension.ts]
   Extension --> Context[src/core/context.ts]
   Extension --> Registry[src/registry.ts]
-  Registry --> Modules[src/modules/*]
+  Registry --> Modules[semantic module folders]
   Modules --> Shared[src/shared/*]
   Modules --> Core[src/core/*]
+  Context --> Device[src/device/*]
   Prefs[src/prefs.ts] --> PrefsMetadata[src/prefsMetadata.ts]
   PrefsMetadata -. mirrors .-> Registry
   Schema[data/schemas/*.xml] -. validates settings .-> Registry
@@ -26,11 +27,17 @@ flowchart TD
 ```text
 src/
   core/                  Extension context, settings, and logging
+  clipboard/             Clipboard history module and UI
+  desktop/               Desktop-only modules such as tray icons
   dev/                   Developer-only tools
-  modules/               Feature modules registered in the extension
-    ...                  One folder per regular Aurora module
+  device/                Runtime target and hardware capability detection
+  dock/                  Dock module and dock-specific helpers
+  panel/                 GNOME panel and Quick Settings integrations
+  patches/               Focused Shell behavior patches and monkey-patches
+  privacy/               Privacy and screen-sharing behavior
   shared/                Utilities shared by modules
   styles/                SCSS partials compiled into Shell stylesheets
+  theme/                 Theme and color-scheme modules
 ```
 
 ## Runtime Lifecycle
@@ -80,13 +87,15 @@ classDiagram
     +title string
     +subtitle string
     +options ModuleOption[]
+    +runtime ModuleRuntimePolicy
     +factory(context) Module
   }
 
   class ExtensionContext {
     +uuid string
     +path string
     +settings SettingsManager
+    +device DeviceService
   }
 
   ModuleDefinition --> Module : creates
@@ -97,6 +106,11 @@ Each module owns its runtime behavior and cleanup. `enable()` and `disable()` mu
 actors, signal handlers, timeouts, D-Bus watches, and injected Shell UI must be removed by the same
 module that created them.
 
+`ModuleDefinition.runtime` is optional. When omitted, the module is treated as desktop-only. Use
+`targets: ['shared']` only for modules that are intentionally valid on both desktop and future
+mobile runtimes. Hardware-specific modules should declare `requires` capabilities instead of
+probing and failing late inside `enable()`.
+
 ## Registry And Preferences
 
 Every registry module must stay in sync across:

CONTRIBUTING.md

@@ -13,33 +13,35 @@ graph TD
 
     A["extension.ts"] -->|Injects| B["ExtensionContext"]:::core
     B -->|Provides| C["SettingsManager"]:::core
-    B -->|Provides| D["ShellEnvironment"]:::adapter
+    B -->|Provides| D["DeviceService"]:::adapter
 
     E["Module"]:::core -->|uses| B
 
-    M["modules/*.ts<br/>(class + definition)"]:::core -->|definition export| F["registry.ts"]:::core
+    M["semantic folders<br/>(class + definition)"]:::core -->|definition export| F["registry.ts"]:::core
     F -->|Definitions + factory| A
     P["prefsMetadata.ts"]:::core -->|Metadata mirror| G["prefs.ts (Generic UI)"]
 ```
 
-1.  **Dependency Injection:** `extension.ts` instantiates an `ExtensionContext` and injects it into every module. **Modules must never use GNOME Shell globals (like `Main`, `Gio.Settings`) directly.**
+1.  **Dependency Injection:** `extension.ts` instantiates an `ExtensionContext` and injects it into every module. Modules read Aurora settings through `this.context.settings`; direct imports of GNOME Shell APIs such as `Main` are expected for Shell UI integration.
 2.  **Abstractions:**
     - Use `this.context.settings` to interact with GSettings.
-    - Use `this.context.shell` for Shell-wide status (e.g., startup check, overview).
-    - This allows for easier mocking during unit tests.
+    - Use `this.context.device` for runtime target and hardware capabilities.
+    - Keep pure logic outside Shell imports when it needs unit coverage.
 3.  **Layering:** Separate UI orchestration (Clutter actors) from pure business logic. Complex logic should be extracted into standalone TypeScript functions or classes.
 4.  **Self-Registering Modules:** Each module file exports a `definition: ModuleDefinition` co-located with its class, including the factory that constructs it. `src/registry.ts` is a pure aggregator — it imports every `definition` and returns them in UI order. `extension.ts` iterates the registry and calls `def.factory(ctx)` directly; no central factory map exists.
 5.  **Metadata-Driven Preferences:** The preferences UI is generated dynamically from `src/prefsMetadata.ts`, a hand-maintained metadata mirror. Prefs cannot import `registry.ts` because it runs in `gnome-extensions-app` (GTK/Adw), which cannot resolve `resource:///org/gnome/shell/*` imports pulled in transitively by module classes. Parity between `registry.ts`, `prefsMetadata.ts`, and the GSettings schema is enforced by `tests/unit/registry.test.ts`.
 
 ## Adding a Module
 
-1. Create `src/modules/myModule/myModule.ts` with a `Module` subclass **and** a co-located `definition` export. Every module **must** live in its own folder named after the module (e.g., `dock/dock.ts`, `trayIcons/trayIcons.ts`). For complex modules, split supporting logic into sibling files inside that folder (e.g., `trayIcons/sniHost.ts`, `trayIcons/trayContainer.ts`):
+1. Choose the semantic source area, then create a `Module` subclass **and** a co-located `definition` export. Single-file modules can live directly in their area, for example `src/patches/myPatch.ts`; complex modules should use a subfolder, for example `src/panel/myPanelFeature/myPanelFeature.ts`.
+
+Current source areas are `dock`, `panel`, `desktop`, `patches`, `theme`, `privacy`, and `clipboard`. Use `desktop` for desktop-only features such as tray icons. Add future hardware probes under `device`, not inside feature modules.
 
 ```typescript
 import { gettext as _ } from 'gettext';
 
 import type { ExtensionContext } from '~/core/context.ts';
-import type { ModuleDefinition } from '~/moduleDefinition.ts';
+import type { ModuleDefinition } from '~/module.ts';
 import { Module } from '~/module.ts';
 
 export class MyModule extends Module {
@@ -59,8 +61,10 @@ export class MyModule extends Module {
 export const definition: ModuleDefinition = {
   key: 'my-module',
   settingsKey: 'module-my-module',
+  section: 'behavior',
   title: _('My Module'),
   subtitle: _('Description'),
+  runtime: { targets: ['desktop'] },
   options: [
     // (Optional) add sub-settings here
     { key: 'my-sub-key', title: _('Sub Setting'), subtitle: _('...'), type: 'switch' },
@@ -72,7 +76,7 @@ export const definition: ModuleDefinition = {
 2. Register the definition in `src/registry.ts` — one import line plus one array entry (preserve UI order):
 
 ```typescript
-import { definition as myModule } from '~/modules/myModule/myModule.ts';
+import { definition as myModule } from '~/patches/myPatch.ts';
 
 export function getModuleRegistry(): ModuleDefinition[] {
   return [
@@ -88,6 +92,7 @@ export function getModuleRegistry(): ModuleDefinition[] {
 {
   key: 'my-module',
   settingsKey: 'module-my-module',
+  section: 'behavior',
   title: _('My Module'),
   subtitle: _('Description'),
   options: [