---

name: frontend description: Frontend development context for the Megahub project. Use when working on the web-based IDE, Vite build system, Blockly visual programming, Web Bluetooth API integration, JavaScript frontend code, CSS/styles, UI components, or anything in the /frontend/ directory.

Frontend Development — Megahub IDE

Tech Stack

• Vite — build tool and dev server
• Blockly 12.3.1 — visual programming editor; custom blocks in /frontend/src/components/blockly/ — see blockly skill for block authoring, Lua generators, and BLOCKS.md generation
• Vanilla JS — no framework (intentionally lightweight for ESP32 flash size)
• Web Bluetooth API — browser BLE, Chrome/Edge/Opera only
• Prism.js — Lua syntax highlighting in the preview panel
• Web Components — all sidebar panels are custom elements with Shadow DOM

Build Modes

| Mode | Description | |------|-------------| | dev | Hot reload, localStorage for persistence, no BLE | | bt | Production BLE mode, deployed to GitHub Pages | | web | WiFi/HTTP mode, served from firmware WebServer |

Mode is available at runtime as import.meta.env.VITE_MODE.

---

File Structure

frontend/
  index.html                  Main entry point (HTML skeleton)
  src/
    index.js                  App controller, event wiring, all Application.* methods
    bleclient.js              BLE protocol client (fragmentation, streaming, events)
    theme.css                 CSS design tokens (all --vscode-* variables)
    styles.css                Global styles, layout grid, all UI component CSS
    components/
      blockly/                Blockly editor + custom block definitions
      files/                  Project manager dialog (list/create/delete/autostart)
      logger/                 Terminal-style log output (max 50 entries)
      luapreview/             Syntax-highlighted Lua code preview
      portstatus/             Real-time LEGO port status cards
      ui/                     show_value block output display
      btdevicelist/           Bluetooth Classic device list + discovery
      sidebar-toggle/         Mobile sidebar toggle button

---

VS Code Dark Theme System

All design tokens are CSS custom properties defined in theme.css. Always use these — never hardcode colors or sizes.

Key Color Tokens

--vscode-bg-primary: #1e1e1e      /* Main background */
--vscode-bg-secondary: #252526    /* Panels, cards, sidebar */
--vscode-bg-elevated: #2d2d30     /* Hover states */
--vscode-bg-input: #3c3c3c        /* Form inputs */

--vscode-text-primary: #cccccc    /* Main text */
--vscode-text-secondary: #858585  /* Muted text, breadcrumb items */
--vscode-text-tertiary: #6a6a6a   /* Very muted (separators) */
--vscode-text-bright: #ffffff     /* Headings, active labels */

--vscode-accent-blue: #007acc     /* Focus borders */
--vscode-accent-blue-dark: #0078d4 /* Primary buttons, status bar */
--vscode-accent-blue-hover: #1177bb
--vscode-accent-teal: #4ec9b0     /* Success, connected state */
--vscode-accent-yellow: #dcdcaa   /* Warning, connecting state */

--color-success: #4ec9b0
--color-error: #f48771
--color-error-bg: #5a1d1d
--color-warning: #dcdcaa

--vscode-border-light: #3c3c3c
--vscode-border-medium: #3e3e42

Key Spacing / Sizing Tokens

--spacing-xs: 0.25rem   --spacing-sm: 0.5rem
--spacing-md: 0.75rem   --spacing-lg: 1rem
--spacing-xl: 1.25rem   --spacing-2xl: 1.5rem

--transition-fast: 0.15s ease
--transition-medium: 0.3s ease

--header-height: 3rem
--z-modal: 1100   --z-tooltip: 2000

---

Application Mode System

Three modes, switched via Application.setMode(mode):

| Mode | View shown | |------|-----------| | btconnect | Welcome screen + connect button | | management | Project list (files component) | | editor | Blockly editor + sidebar controls |

Visibility Mechanism

dynamicvisibility class (all modes):

// setMode() sets display:block/none on elements with class dynamicvisibility
// Elements also have class visible-{mode} to declare when they appear
// e.g. class="dynamicvisibility visible-editor visible-management"

⚠ setMode() always sets display: block — do NOT use dynamicvisibility for elements that need display: flex or display: grid.

body.dataset.mode (CSS-based, for flex/grid elements):

// setMode() also sets document.body.dataset.mode = mode
// Use CSS selectors: body[data-mode="editor"] .my-element { display: flex }
// Used by: header breadcrumb, back button

---

Layout Grid

┌──────────────────────────────────────┐  ← header (3rem)
│ [←] Megahub IDE / project  [toggle] │
├──────────────────┬───────────────────┤  ← 1fr
│                  │ sidebar buttons   │
│  Blockly /       │ ─────────────────│
│  Files /         │ accordion panels  │
│  Welcome         │  lua / ports /   │
│                  │  ui / btdevices  │
├──────────────────┴───────────────────┤  ← footer (8–12rem)
│  Logger (terminal output)            │
├──────────────────────────────────────┤  ← statusbar (20px)
│ ● Connected to Megahub IDE           │
└──────────────────────────────────────┘

Desktop (≥1512px): 75/25 content/sidebar split. Mobile: sidebar is a slide-in overlay.

---

Existing UI Patterns (use these, don't reinvent)

Notifications (Toast)

showNotification('success' | 'error' | 'warning' | 'info', title, message, durationMs)
// duration 0 = no auto-dismiss
// Returns the notification element (for manual dismissal)

Confirmation Dialog

const confirmed = await showConfirmDialog(title, message, {
  confirmText: 'Delete',   // default: 'Confirm'
  cancelText: 'Cancel',
  destructive: true        // red confirm button (default: true)
});

Top Progress Bar

Progress.show()   // indeterminate shimmer sweep
Progress.hide()
// Used for: project list load, file open, file save

BLE Connection Modal

ConnectionModal.show()              // resets all steps to pending
ConnectionModal.setStep(stepId)     // marks previous steps done, current active
ConnectionModal.setAllDone()        // all checkmarks
ConnectionModal.setError(stepId, message)  // marks step red, shows error text
ConnectionModal.hide()
// stepIds: 'requesting' | 'connecting' | 'services' | 'notifications' | 'mtu' | 'ready'

VS Code Status Bar

StatusBar.setConnecting()
StatusBar.setConnected(deviceName)
StatusBar.setDisconnected()
StatusBar.setMessage(text)   // right-side info text
StatusBar.clearMessage()

Sidebar Icon Buttons

.sidebar-icon-btn                   /* base */
.sidebar-icon-btn-primary           /* blue background (Execute) */
.sidebar-icon-btn-danger            /* red background (Stop) */
.sidebar-icon-btn-save              /* neutral, turns blue on hover */
.sidebar-icon-btn-toggle            /* teal when aria-pressed="true" */
.sidebar-icon-btn.btn-loading       /* spins the SVG icon */

---

BLE Client Architecture (bleclient.js)

Connection Flow

connect(onProgress?)
  → navigator.bluetooth.requestDevice()  [requires user gesture]
  → _setupGattConnection(onProgress?)
      → gatt.connect()
      → getPrimaryService()
      → getCharacteristic() × 4
      → startNotifications() × 3
      → sleep(200)  ← CRITICAL: BLE stack propagation delay
      → waitForMTU(2000)
      → testControlChannel()
  → emits onProgress callbacks at each step

Message Protocol

• 5-byte fragment header: type, messageId, fragmentNum(2), flags
• MTU: default 23 bytes, negotiated up to 517 bytes
• Fragmentation: automatic for all requests/responses
• Streaming protocol: for large file uploads (chunks + ACK window)

Event System

bleClient.addEventListener(APP_EVENT_TYPE_*, callback)
bleClient.removeAllEventListeners()
// Event types: LOG, PORTSTATUS, COMMAND, BTCLASSICDEVICES

File Upload

await bleClient.uploadFileStreaming(projectId, filename, content, onProgress?)
// Sliding window: 8 chunks in flight, waits for ACK before advancing

---

Animation Principles

All animations must be purposeful — each one communicates meaning:

| Use case | Animation | Timing | |----------|-----------|--------| | State transitions | CSS transition | var(--transition-fast) = 0.15s ease | | Indeterminate loading | Shimmer sweep (progress bar) | 1.4s linear infinite | | Spinner (waiting) | Rotate 360° | 0.8s linear infinite | | Step completion | Scale 0→1 + opacity | 0.15s ease-out (one-shot) | | Status dot state change | Color transition | 0.3s ease | | Connecting pulse | Opacity 1→0.3→1 | 1s ease-in-out infinite |

Always wrap looping animations in:

@media (prefers-reduced-motion: reduce) {
  /* replace animation with instant state */
}

---

Component Pattern (Web Components)

All sidebar panels are custom elements with Shadow DOM:

class MyComponent extends HTMLElement {
  connectedCallback() {
    const shadow = this.attachShadow({ mode: 'open' });
    const sheet = new CSSStyleSheet();
    sheet.replaceSync(styleSheet);   // import from style.css
    shadow.adoptedStyleSheets = [sheet];
    shadow.innerHTML = template;     // import from component.html
  }
}
customElements.define('custom-my-component', MyComponent);

Accordion behavior: dispatch accordion-expand / accordion-collapse custom events. Parent (initSidebarAccordion() in index.js) collapses all others on expand.

---

Important Constraints

• Bundle size: Keep JS small — it's embedded in 4MB ESP32 flash
• No framework: No React/Vue/Angular — intentional
• Shadow DOM: Component styles are isolated; theme.css variables are inherited through the shadow boundary
• Web Bluetooth: User gesture required for requestDevice() — never call without a click handler
• Supported browsers: Chrome, Edge, Opera only — Firefox/Safari don't support Web Bluetooth