# AmebaPro3 Control Panel Development Agent Specification (agents.md)

## Project Overview

A Windows desktop control panel for Realtek AmebaPro3 SoC bring-up, debugging, and automation.

Target stack:

* C#
* .NET 8
* WPF (preferred over WinForms)
* Windows 11-like modern styling using native WPF only
* Phase 1: UI-only skeleton (baseline, no real hardware access)

Goals:

* Modern, clean, engineering-oriented UI
* Stable build and runtime (no third-party UI dependencies)
* Layout and component structure that supports future services (UART, J-Link, flashing)

---

## UI Framework & Styling (STRICT)

### Mandatory

* Framework: WPF
* Target: .NET 8 (e.g. net8.0-windows)
* No third-party UI libraries (no theme packages)
* Style target: Windows 11-like (cards, rounded corners, subtle borders, simple states)
* Styling technique: XAML ResourceDictionaries + Styles + ControlTemplates

### Forbidden

* x WPF-UI / lepoco, MahApps, MaterialDesign, FluentWPF, HandyControl, etc.
* x UWP / WinUI 3
* x Windows Store dependency
* x Runtime hardware access in Phase 1

---

## Architecture Principles

* UI-first development
* MVVM-friendly
* Clear separation between:
  * UI (Views + ViewModels)
  * Device services (UART/J-Link services)
  * Debug services (future)
* Every device/session has independent console and command history
* Console/log UI must stay responsive under heavy output

---

## Solution Structure

* `App.xaml`
  * Loads theme resources (Light by default)
* `Themes/Colors.Light.xaml` / `Themes/Colors.Dark.xaml`
* `Themes/Controls.xaml` (Button/TextBox/TabControl/List styles)
* `Views/MainWindow.xaml`
* `Views/Pages/MainPage.xaml`
* `Views/Pages/JLinkPage.xaml`
* `Views/Controls/ConsolePanel.xaml` (reusable)
* `ViewModels/*`
* `Services/Uart/*`
* `Scripts/uart_bridge.py`

---

## Styling Contract (native WPF)

* Font: Segoe UI Variable (fallback: Segoe UI)
* Buttons: height 36, radius 10, consistent padding
* Inputs: radius 10, clear focus border
* Cards: radius 12, subtle border, optional very light shadow
* Accent color used only for primary actions / selected tab / selected nav

---

## Main Application Layout

### MainWindow.xaml

Purpose: Host top navigation + page content.

Root Layout:

* `Grid`
  * `Row 0` = `Auto` (TopBar)
  * `Row 1` = `*` (PageContent)
  * `Row 2` = `Auto` (StatusBar)

Row 0: TopBar (Auto, ~56px)

* Left: App title `TextBlock` ("AmebaPro3 Control Panel")
* Right: `ListBox` navigation for page switching
  * Tab 1: Panel (MainPage)
  * Tab 2: Debugger (JLinkPage)
* Optional theme toggle or window buttons

Row 1: PageContent

* `ContentControl` bound to `CurrentPageViewModel`

Row 2: StatusBar (Auto, ~28px)

* Left: Selected device + connection status text
* Right: `Last RX time`, `RX bytes`, `TX bytes`

Naming (important):

* Main container: `MainRootGrid`
* Page host: `MainContentHost`

---

## Pages

### 1) MainPage.xaml (Panel)

Purpose: Combine Flash Image, Arduino control, and AmebaPro3 UART in a split layout.

Root Layout:

* `Grid` with two columns
  * Column 0 (Left, wider): `*` (AmebaPro3 UART)
  * Column 1 (Right, narrower): ~480 (Flash + Arduino)
  * Column gap: 12

Column 0: AmebaPro3 UART (largest area)

* A single `ConsolePanel` instance configured for AmebaPro3
* Header controls inside ConsolePanel:
  * COM port dropdown
  * Baud rate input (default 1500000)
  * Connect / Disconnect button
  * Optional TeraTerm launch button

Column 1: Right stack

* `Grid` with rows and a splitter:
  * Row 0 = Auto (Flash Card)
  * Row 1 = 8 (Spacing)
  * Row 2 = * (Arduino Card)

#### Flash Image Card (Row 0, Auto)

Card container: `Border` (CardStyle)
Contents:

* Section title: `TextBlock` "Flash Image"
* `Grid` with rows:
  * Bootloader file picker (`TextBox` readonly + `Browse` button)
  * Application file picker (`TextBox` readonly + `Browse` button)
  * `Flash Image` primary button (full width)

Control names:

* `BootloaderPathTextBox`, `BrowseBootloaderButton`
* `AppPathTextBox`, `BrowseAppButton`
* `FlashImageButton`

#### Arduino Controller Card (Row 2, *)

Card container: `Border` (CardStyle)
Contents (top to bottom):

1. Connection row:
   * COM dropdown + Baud textbox (default 115200) + Connect button
2. Mode buttons (uniform size, aligned, share whole row width):
   * Reset, Download Mode, Normal Mode, Test Mode
3. Test mode selector:
   * `ComboBox` "Test 1" to "Test 7"

Control names:

* `ArduinoComComboBox`, `ArduinoBaudTextBox`, `ArduinoConnectButton`
* `ArduinoResetButton`, `ArduinoDownloadButton`, `ArduinoNormalButton`, `ArduinoTestModeButton`
* `ArduinoTestSelectComboBox`

---

### 2) JLinkPage.xaml (Debugger)

Purpose: Multi-AP debugging for AmebaPro3.

Root Layout:

* `Grid` with columns:
  * Column 0 = `*` (Main AP console workspace)
  * Column 1 = `280` (AP selector pane)
  * Column gap: 12

Top area (inside Column 0, Row 0 Auto):

* J-Link selection row:
  * `ComboBox` for J-Link serial number
  * `Refresh` button (optional)
  * `Connect` button (Phase 1 dummy)

Workspace area (Column 0, Row 1 *):

* `ContentControl` showing selected AP view
* Each AP view contains one `ConsolePanel` configured for that AP

Right AP selector pane (Column 1):

* Card container + `ListBox` (navigation style)
* Items:
  * Cortex M33 - Processor NP
  * Cortex M33 - Processor MP
  * Cortex M23 - Processor FP
  * Cortex CA32 - Processor AP

AP selector control name:

* `ApSelectorListBox`

AP sessions:

* Each AP has independent ConsolePanel state (log + history + command input)

Debugger command buttons (inside ConsolePanel `CommandButtons` slot):

* Halt, Continue, Step In, Step Over, Step Out
* File picker that lets user load multiple commands from file
* Command logic should support all JLink basic commands

Notes:

* When AP connected, Phase 2+ should not halt CPU by default
* Designed to integrate Segger J-Link + GDB later

---

## Reusable UI Components

### ConsolePanel.xaml (Core component)

Must be reusable across:

* AmebaPro3 UART
* Arduino UART (optional)
* J-Link AP sessions

#### ConsolePanel Layout (codex-ready)

Root: `Grid`

* Row 0 = Auto (Header, ~48px)
* Row 1 = * (Log viewer)
* Row 2 = Auto (GridSplitter)
* Row 3 = * (History list, min ~140px)
* Row 4 = Auto (CommandButtons slot)
* Row 5 = Auto (Actions row)
* Row 6 = Auto (Input row, ~44px)

Row 0: Header

* Left: `Title` + status text
* Right: header content slot (page-specific controls)

Row 1: Log viewer

* Must support horizontal + vertical scrolling
* Read-only
* Monospace option
* Performance: use a virtualization-friendly approach
* Can scroll up, down, left, right
* `ListBox`/`ItemsControl` virtualized lines (one line per item)

Row 3: Command history

* `ListBox` (virtualized)
* Behaviors:
  * Latest command at bottom
  * No duplicate command entries
  * Up/Down navigates history
  * Single click selects and fills command input
  * Double click sends command

Row 5: Actions row

* Clear, Save, Load Commands

Row 6: Input row

* `Grid` with columns:
  * Column 0 = * command input `TextBox`
  * Column 1 = 8 spacing
  * Column 2 = Auto send `Button`
* Press Enter triggers Send
* After send: clear input

Optional slot: `CommandButtons` area (for debugger step/halt/continue)

* Placed between history and actions row

#### ConsolePanel Public Bindings (ViewModel properties)

* `string Title`
* `bool IsConnected`
* `ObservableCollection<string> LogLines`
* `ObservableCollection<string> History`
* `string CurrentCommand`
* `ICommand SendCommand`
* `ICommand ClearLog`
* `ICommand SaveLog`
* `ICommand LoadCommandFileCommand`
* `UIElement CommandButtonsContent` (optional)

---

## Phase Roadmap

### Phase 1 (Baseline)

* UI-only
* All pages render correctly
* Dummy content / placeholder logs
* No hardware access

### Phase 2 (In progress)

* UART service (AmebaPro3) using Python + pyserial bridge (`Scripts/uart_bridge.py`)
* Optional TeraTerm launch integration
* Implement history behaviors

### Phase 3

* J-Link session management
* Multi-AP GDB integration
* Session lifecycle control

### Phase 4

* Flash pipeline
* C++ integration (Prefer)
* Python tool integration
* Automation & scripting

---

## Coding Rules for Agents

* Keep UI logic independent
* No blocking calls on UI thread
* One function = one job
* Prefer clarity over cleverness
* Engineering tool mindset

---

## Summary

This project is a professional SoC control panel focused on:

* Clarity
* Stability (no UI library dependencies)
* Expandability
* Multi-device / multi-session workflows

UI correctness and structure come before any hardware logic.