# AetherDesk AI PC Refactor Roadmap

Generated: 2026-07-01

Purpose: preserve the velocity of the current AI PC prototype while giving the next engineering pass a safe path to make it maintainable.

Do not begin this refactor until the served-preview validation gates have been exercised. Fix obvious runtime failures first, then consolidate.

## Current situation

The AI PC shell has many appended self-contained browser modules in:

```text
C:\Users\issda\AetherDesk\aetherdesk\public\real-pc-shell.js
C:\Users\issda\AetherDesk\aetherdesk\public\real-pc-shell.css
```

This was useful for fast progress because each surface could be added safely and locally. The tradeoff is that document-level listeners, z-index ownership, localStorage keys, and overlay lifecycles are now spread across many independent IIFEs.

## Refactor goal

Create one maintainable operator subsystem without changing the product behavior:

- one shell lifecycle
- one keyboard router
- one overlay manager
- one toast/status service
- one local state service
- one manifest-backed shortcut registry
- one validation-backed acceptance path

## Non-goals

- Do not redesign the visual language during this refactor.
- Do not remove features just because they were added quickly.
- Do not change shortcuts unless there is a proven collision.
- Do not delete localStorage keys without a migration or Preferences action.
- Do not require a backend for local-first behavior.

## Proposed module boundaries

### `AetherDeskShellRuntime`

Owns startup and safe boot:

- waits for `.real-pc-shell`
- applies Safe Mode from URL/localStorage
- mounts persistent surfaces
- exposes a small `window.aetherdeskAIpc` debug/control object

### `KeyboardRouter`

Owns all global shortcuts:

- search/help/control map
- mission modes
- request bar and queue
- snapshots and handoff
- preferences and safe mode
- window switcher/recovery/tiling

Rules:

- one capture listener
- no duplicate global key listeners
- inputs/textareas opt out unless the shortcut is explicitly global
- all shortcuts registered from one data table

### `OverlayManager`

Owns modal overlays:

- Quick Help
- Control Map
- Mission Modes
- Agent Request Bar
- Agent Queue
- Snapshot Viewer
- Preferences
- Window Switcher

Rules:

- one overlay stack
- Escape closes top overlay
- only one command overlay active unless explicitly allowed
- Safe Mode closes transient overlays

### `PersistentSurfaceManager`

Owns always-visible surfaces:

- Mission dock
- AI status HUD
- backend sync pill
- first-run operator hint

Rules:

- surfaces respect Safe Mode
- surfaces have explicit z-index bands
- surfaces expose refresh methods
- surfaces do not own unrelated keyboard shortcuts

### `LocalStateStore`

Owns `aetherdesk.realPc.*` state:

- operator session
- request queue
- handoff receipts
- black-box snapshots
- backend sync status/history
- collapse preferences
- safe mode

Rules:

- typed-ish read/write helpers
- corrupt JSON fallback
- small bounded histories
- Preferences is the only general clear/reset UI

### `WindowOps`

Owns desktop window operations:

- activate
- minimize/park
- restore
- switcher ordering
- snap left/right
- maximize
- center
- z-index policy

Rules:

- use one z-index allocator
- do not duplicate active-window logic
- keep taskbar-safe bounds centralized

### `BackendSyncBridge`

Owns request sync:

- file preview local-only status
- served preview sync attempt
- `/api/pc/agent-task` request shape
- backend metadata on queue items
- sync history

Rules:

- never break local queue if backend fails
- never require backend for core desktop use
- expose manual sync
- report status through state/pill/HUD

### `ProofAndHandoff`

Owns receipts and snapshots:

- markdown handoff
- black-box snapshot collection
- snapshot viewer
- clipboard fallback

Rules:

- avoid secrets
- capture useful window/state context
- keep history bounded

## CSS consolidation plan

Move appended CSS blocks into grouped sections inside `real-pc-shell.css`:

1. base shell and desktop
2. windows/taskbar/start
3. compact short-screen mode
4. persistent AI PC surfaces
5. overlays
6. keyboard/focus states
7. Safe Mode
8. proof/preferences/sync utilities

Keep comments marking each section. Do not minify during active development.

## Shortcut registry target

Represent shortcuts as data, then render Control Map and Quick Help from the same registry.

Example fields:

```json
{
  "keys": "Ctrl+Alt+Enter",
  "label": "Ask the AI PC",
  "surface": "agent_request_bar",
  "group": "Agent",
  "handler": "openAgentRequestBar"
}
```

Benefits:

- fewer mismatches between docs, manifest, and runtime
- easier conflict detection
- easier future customization

## LocalStorage ownership table

| Key | Owner | Notes |
| --- | --- | --- |
| `aetherdesk.realPc.session` | existing desktop session | preserve current behavior |
| `aetherdesk.realPc.operatorSession` | LocalStateStore / Mission dock | objective, next, notes, mission mode |
| `aetherdesk.realPc.operatorSessionCollapsed` | PersistentSurfaceManager | mission dock collapse |
| `aetherdesk.realPc.operatorHintDismissed` | PersistentSurfaceManager | first-run hint |
| `aetherdesk.realPc.aiStatusHudCollapsed` | PersistentSurfaceManager | HUD collapse |
| `aetherdesk.realPc.agentRequestQueue` | LocalStateStore / Queue | bounded queue |
| `aetherdesk.realPc.handoffReceipts` | ProofAndHandoff | bounded history |
| `aetherdesk.realPc.blackBoxSnapshots` | ProofAndHandoff | bounded history |
| `aetherdesk.realPc.backendSyncStatus` | BackendSyncBridge | current sync state |
| `aetherdesk.realPc.backendSyncHistory` | BackendSyncBridge | bounded sync history |
| `aetherdesk.realPc.safeMode` | AetherDeskShellRuntime | panic recovery |

## Z-index bands

Proposed bands:

- base shell: current shell layer
- windows: existing window z-index allocator
- persistent surfaces: `2147480080` to `2147480099`
- toasts: `2147480110`
- overlays: `2147480120` to `2147480199`
- emergency/safe surfaces: highest only if needed

Avoid creating new arbitrary z-indexes after consolidation.

## Validation before refactor

Before moving code, collect evidence for:

- static smoke pass
- localhost shell load
- short-screen viewport
- keyboard navigation
- window switcher/tiling/recovery
- mission/request/queue flow
- proof/handoff flow
- Safe Mode

Use:

```text
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_VALIDATION_REPORT_TEMPLATE.md
C:\Users\issda\AetherDesk\aetherdesk\public\aetherdesk-ai-pc-acceptance-gates.json
```

## Refactor sequence

1. Capture a validation report so current behavior is known.
2. Add a single `window.aetherdeskAIpc` namespace without moving logic yet.
3. Move shared helpers first: escaping, JSON read/write, toast, app open, shortcut dispatch.
4. Introduce `KeyboardRouter` and migrate shortcuts one group at a time.
5. Introduce `OverlayManager` and migrate overlays one at a time.
6. Introduce `LocalStateStore` and migrate localStorage calls.
7. Introduce `WindowOps` and migrate switcher/tiling/recovery.
8. Introduce `BackendSyncBridge` and migrate sync logic.
9. Re-run static smoke and visual gates after each migration batch.
10. Update manifest/docs only after behavior is confirmed.

## Stop conditions

Stop refactor and fix immediately if:

- Start/search stops focusing
- Safe Mode cannot be toggled
- request queue loses data
- windows cannot be restored
- Control Map no longer launches actions
- backend failure breaks local request capture
- short-screen viewport becomes unusable

## Definition of a good refactor pass

A good pass changes structure without making the product less true:

- same or better operator behavior
- fewer duplicate listeners
- fewer scattered state writes
- clearer ownership
- updated smoke/gates/docs
- validation report shows no critical regressions

## Next best engineering action

Do not add more AI PC surfaces until a served-preview validation report exists.

The best next action is:

```powershell
node C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-static-smoke.js
powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-launch.ps1
node C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-create-validation-report.js --validator "agent" --preview-url "http://127.0.0.1:5717/?resetDesktop=1" --viewports "1280x720,900x520" --backend-mode "static-preview"
```

Then fill the generated validation report with real runtime evidence.
