tcad-bodeplot/uart_example/implementation_plan_Single_web_uart_terminal.md

# Implementation Plan - Web UART Terminal

This plan details the implementation of a modern, responsive, and feature-rich Web UART Terminal application. The design will match the dark-themed UI provided in the user's reference image and support the Web Serial API for real-time serial communication with hardware.

## User Review Required

> [!IMPORTANT]
> **Browser Compatibility**: The Web Serial API is supported in Chromium-based browsers (Chrome, Edge, Opera). It is not supported by default in Firefox or Safari. A friendly warning banner will be displayed to users accessing the page from unsupported browsers.
> **Local Server Requirement**: The Web Serial API requires a secure context (HTTPS) or localhost to work. To facilitate this, we will configure a simple dev environment using **Vite** so you can run it locally with `npm run dev` (serving at `http://localhost:5173`).

## Proposed Changes

We will create a self-contained, lightweight, and high-performance Vanilla HTML/CSS/JS application within the `/home/roy/zData/WTPCode/pec930/pec930_pfc_llc/ui/uart_terminal` directory.

### UI & Dev Environment Configuration

---

#### [NEW] [package.json](file:///home/roy/zData/WTPCode/pec930/pec930_pfc_llc/ui/uart_terminal/package.json)
- Define a project package with `vite` as a dev dependency.
- Include scripts for local development (`npm run dev`) and building (`npm run build`).

#### [NEW] [vite.config.js](file:///home/roy/zData/WTPCode/pec930/pec930_pfc_llc/ui/uart_terminal/vite.config.js)
- A basic configuration file for Vite to ensure it runs correctly and resolves static assets.

#### [NEW] [index.html](file:///home/roy/zData/WTPCode/pec930/pec930_pfc_llc/ui/uart_terminal/index.html)
- Create the HTML skeleton of the UART Terminal.
- Match the layout in the screenshot:
  - Header: App Title, Theme Toggle button.
  - Action Control: Connect/Disconnect button (circle with play/stop icon), Download button (square download icon).
  - Info Banner: "Not connected" warning banner, dynamically changing based on serial connection status.
  - Serial Settings Grid: Dropdowns for Baud Rate, Data Bits, Stop Bits, Parity.
  - Received Data Section: Section title, controls (Scroll: Auto-scroll/None, Display: Auto/Hex/Text), console output textarea/container.
  - Send Data Footer: Form input with keyboard shortcut tooltip, Send Format dropdown (ASCII/Hex), Send button, and Clear Terminal (trash) button.
- Embed all required SVG icons inline for zero external dependencies and fast load times.
- Include a Google Font link (e.g., "Inter" for UI typography, "JetBrains Mono" for the terminal console).

#### [NEW] [index.css](file:///home/roy/zData/WTPCode/pec930/pec930_pfc_llc/ui/uart_terminal/index.css)
- Implement a premium design system using CSS custom properties (variables) for HSL colors.
- Support Dark Mode (default) and Light Mode.
- Incorporate subtle animations (transitions on hover/active, pulsing connection status, smooth modal fades).
- Implement responsive grids and flex layouts, ensuring pixel-perfect alignment with the reference image.
- Design custom scrollbars for the terminal output.

#### [NEW] [app.js](file:///home/roy/zData/WTPCode/pec930/pec930_pfc_llc/ui/uart_terminal/app.js)
- Implement core UART logic via Web Serial API:
  - Request serial port and open connection using selected settings (Baud Rate, Data Bits, Stop Bits, Parity).
  - Background reading loop with cancellation support.
  - Writing loop supporting ASCII/Hex conversion.
- Implement helper utilities:
  - Hex parser (validating and converting hex string inputs like `AA BB CC` or `AABBCC` to Uint8Array).
  - Hex formatter (representing received bytes as spaced hex strings e.g. `00 12 AF`).
- Implement UI interactions:
  - Terminal text appending with Auto-scroll capability.
  - Download log: converts terminal content to a `.txt` blob and triggers a browser download.
  - Clear log: clears the screen and reset states.
  - Keyboard shortcuts (e.g. `Ctrl+Enter` to send, `Ctrl+Tab` to insert tab in input, etc.).
  - Theme toggling with `localStorage` persistence.

#### [NEW] [README.md](file:///home/roy/zData/WTPCode/pec930/pec930_pfc_llc/ui/uart_terminal/README.md)
- Instructions on installing dependencies (`npm install`) and launching the development server (`npm run dev`).
- Quick notes on Web Serial browser compatibility and security requirements.

## Verification Plan

### Manual Verification
1. Launch the local dev server using `npm run dev`.
2. Access the app via Chrome or Edge browser.
3. Verify that the UI matches the reference screenshot (dark theme, layouts, styling, icons, font sizes).
4. Verify the theme toggle (switching from dark to light mode and back).
5. Verify inputs:
   - Check if serial configuration dropdowns have correct options.
   - Verify that clicking "Connect" triggers the browser's Serial Port prompt.
   - Verify Hex transmission (e.g., inputting `48 45 4C 4C 4F` in Hex mode sends `HELLO`).
   - Verify Text transmission.
   - Test "Clear" (trash bin) and "Download" buttons.
   - Test auto-scroll behaviour with mock data.