Desktop Vibe-Coding v3.8

Aurora can live-modify the desktop per user. Say "Make my desktop more minimal" or "Add a clock widget" — and Aurora modifies the real desktop code at runtime. Every user can have a uniquely customized desktop, with full rollback capability.

How It Works

Niuton's desktop is split into two layers:

Layer	Description	Modifiable?
Hard Kernel	Authentication, Window Manager, iframe sandbox, core APIs	No
Soft Shell	Theme/colors, dock, panel, widgets, window chrome, app grid	Yes — by Aurora

Aurora writes per-user component overrides into the database. The client-side desktop-shell.js fetches and injects these overrides on page load. The original desktop.js code remains untouched.

Architecture

Aurora Tool Call (e.g. modify_desktop_theme)
    │
    ▼
api/desktop-components.php
    │ save override to DB
    ▼
niuton_desktop_components (PostgreSQL)
    │
    ▼
desktop-shell.js (client)
    │ fetch on page load
    ▼
NiutonShell.apply()
    ├── CSS → <style> injection
    ├── JS  → Hook-based override
    └── Widget → DOM element in .desktop-area

Modifiable Components

Component	ID	Type	What Can Be Changed
Theme / Colors	theme	css	20+ CSS variables (--accent, --panel-bg, --dock-bg, etc.)
Top Panel	panel	js	Content, height, layout, clock format
Dock	dock	js	Animation, size, style, hover effects
Window Chrome	window-chrome	js	Title bar, buttons, shadows, borders
App Grid	app-grid	js	Icon size, layout, categories
Background	background	css	Wallpaper, particles, animations
Widgets	widget-*	widget	New desktop widgets (clock, weather, etc.)
Context Menu	context-menu	js	Entries, style
Search	search	js	Layout, filters
Shortcuts	shortcuts	js	Keyboard combinations
Animations	animations	css	Transition effects

Aurora Tools

Aurora has 12 tools for desktop modification:

Phase 1: Core Tools

Tool	Parameters	Description
modify_desktop_theme	css_variables: {key: value}	Change CSS variables live
create_desktop_widget	name, html, description	Place a widget on the desktop
remove_desktop_widget	widget_id	Remove a widget
list_desktop_components	—	List all active customizations
reset_desktop_component	component_id	Reset to default
get_desktop_state	—	Current state (theme, widgets, etc.)

Phase 2: Advanced Tools

Tool	Parameters	Description
modify_desktop_component	component_id, code, type	Write a JS/CSS override
read_desktop_component	component_id	Read current override code
preview_desktop_change	component_id, code, duration	10s live preview, then auto-rollback
save_desktop_profile	name	Save entire desktop state as a profile
load_desktop_profile	profile_id	Load a saved profile
modify_desktop_shortcuts	shortcuts: {key: action}	Customize keyboard shortcuts

Hook System

The desktop has 5 hook points where Aurora can inject custom rendering logic:

window.__niutonHooks = {
    renderDockItem: null,       // (app, element) → customize dock items
    renderWindowChrome: null,   // (win, element) → customize title bars
    renderAppGridItem: null,    // (app, element) → customize grid icons
    renderPanelContent: null,   // (panelEl) → customize top panel
    onDesktopReady: null,       // () → run after desktop init
};

When a hook is set, the desktop calls it during rendering. For example, setting renderDockItem lets you change every dock item's appearance.

Widgets

Widgets are HTML+CSS+JS components that float on the desktop. They support:

• Glassmorphism styling — Semi-transparent backdrop with blur
• Draggable — Click and drag to reposition
• Live JavaScript — <script> tags execute safely (validated against blocklist)
• Persistent — Saved in DB, restored on reload

Example: Clock Widget

<div style="font-size: 48px; font-weight: 200; text-align: center; color: #fff;">
    <span id="clock-time"></span>
</div>
<script>
    setInterval(() => {
        const el = document.getElementById('clock-time');
        if (el) el.textContent = new Date().toLocaleTimeString('de-DE');
    }, 1000);
</script>

Profiles

Save your entire desktop customization as a profile and switch between them:

1. Save — save_desktop_profile({name: "Dark Minimal"}) captures all active components
2. Load — load_desktop_profile({profile_id: 3}) restores all components from a profile
3. Reset — reset_desktop_component({component_id: "theme"}) reverts a single component

Profiles are stored in the niuton_desktop_profiles table as JSON snapshots.

Version History

Every component save creates a new version. You can:

• View the version history for any component
• Roll back to any previous version via the API
• The latest active version is always displayed

Widget Management v3.9

Widgets now have an interactive hover toolbar for easy management:

• Hover over any widget to reveal the toolbar
• Drag handle (⠿) — reposition the widget
• Close (✕) — hide the widget (deactivates in DB, can be re-enabled)
• Delete (🗑) — permanently remove the widget with confirmation

The toolbar uses glassmorphism styling and fades in smoothly on hover.

Widget HTML Sanitization

Widget HTML is automatically sanitized before injection to prevent layout issues:

• <!DOCTYPE>, <html>, <head>, <body> tags are stripped
• This prevents widgets from leaking styles onto the desktop background

Settings > Desktop Page

A new "Desktop" page in Settings lets you manage all customizations:

• Quick Actions: Safe Mode activation, Reset All button
• Active Overrides: List of CSS/JS overrides with toggle and delete
• Widgets: List of all widgets with show/hide and delete
• Hooks: Status of registered desktop hooks

Desktop Context Menu

Right-clicking the desktop now shows additional options:

• "Desktop-Anpassungen verwalten" — opens Settings > Desktop
• "Alle Widgets ausblenden" — hides all widgets at once
• "Desktop zuruecksetzen" — resets all overrides with confirmation
• "Safe Mode" — reloads with ?safe=1

Keyboard Shortcut

Ctrl+Shift+S toggles Safe Mode (reloads with/without ?safe=1).

Safe Mode

Append ?safe=1 to the desktop URL to bypass all customizations:

https://your-domain.net/desktop.php?safe=1

This loads the stock desktop without desktop-shell.js, useful for debugging broken overrides.

Security

All injected JavaScript is validated against a blocklist before execution:

Blocked Pattern	Reason
eval(	Arbitrary code execution
Function(	Constructor-based eval (case-sensitive to allow function()
XMLHttpRequest	Prevent external network calls
document.cookie	Cookie theft prevention
localStorage	Storage isolation

Additional safeguards:

• 100KB limit per component
• 2s timeout on JS execution
• Error boundary — try/catch around every injection
• Widget <script> content validated separately from HTML

Database Schema

CREATE TABLE niuton_desktop_components (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL REFERENCES niuton_users(id),
    component_id VARCHAR(50) NOT NULL,
    component_type VARCHAR(20) NOT NULL,  -- 'css', 'js', 'widget'
    code TEXT NOT NULL,
    version INTEGER DEFAULT 1,
    is_active BOOLEAN DEFAULT true,
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(user_id, component_id, version)
);

CREATE TABLE niuton_desktop_profiles (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES niuton_users(id),
    name VARCHAR(100) NOT NULL,
    components JSONB NOT NULL,
    is_default BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT NOW()
);

Files

File	Role
api/desktop-components.php	CRUD API for overrides and profiles
assets/js/desktop-shell.js	Client-side runtime loader
assets/js/desktop.js	5 hook points for override injection
lib/tools.php	12 Aurora tool definitions + executors
desktop.php	Conditional shell.js loading + safe mode