vscode-extension-dev

Extension Architecture

File	Role
src/extension.ts	Entry point — registers commands, activates ConfigPanel
src/ConfigPanel.ts	Webview panel with all tabs (Home, Device, API Keys, AI Providers, Claude.ai, Actions)
src/ConfigManager.ts	Read/write config: include/config.h, server/.env, platformio.ini
src/RelayManager.ts	Spawns/stops server/relay.py as a child process
src/PortDetector.ts	Detects serial ports via PlatformIO → pyserial → PowerShell fallback
package.json	Manifest: commands, views, activity bar, contributes
out/extension.js	Compiled bundle (generated — never edit directly)

Recent behavior to preserve:

• Board env list is read dynamically from platformio.ini sections ([env:...]).
• Selected board env is persisted in .vscode/esp32-display.json.
• Build/flash command includes the selected env (pio run -e <env>).
• Saving config patches only the selected env section in platformio.ini (upload_port, monitor_port, upload_speed).

---

Where Config Is Stored

ConfigManager.save() writes to three files:

File	Fields written
include/config.h	WiFi, API keys, Anthropic/OpenRouter URLs, relay host/port, update interval
server/.env	CLAUDEAI_SESSION, LASTACTIVE_ORG, RELAY_PORT
platformio.ini	selected env section: upload_port, monitor_port, upload_speed

Also written by extension:

File	Purpose
.vscode/esp32-display.json	Persist last selected boardEnv

ConfigManager.load() reads all three and merges them.

---

Tab ↔ Pane Map

Tab button label	data-tab	id="tab-*" pane
🏠 Home	home	tab-home
📡 Device	device	tab-device
🔑 API Keys	apikeys	tab-apikeys
🤖 AI Providers	anthropic	tab-anthropic
☁️ Claude.ai	claudeai	tab-claudeai
⚡ Actions	actions	tab-actions

---

Board-aware flow

1. Device tab board selector (#board-env) is populated from getAvailableEnvs().
2. UI sends boardEnv in build/buildAndFlash messages.
3. Panel backend spawns PlatformIO with -e boardEnv.
4. Config save patches only that env in platformio.ini.

If adding a new board env to platformio.ini, no extra extension code should be required for the selector to show it.

---

Build Commands

All commands run inside vscode-extension/:

cd vscode-extension

# Compile TypeScript (type-check only — does NOT produce out/)
npm run compile

# Fast dev build (produces out/extension.js with source map)
npm run build

# Watch mode (rebuilds on every file save)
npm run watch

# Package into .vsix (runs vscode:prepublish → minified build first)
npm run package

# Build + package + install in one go
npm run package ; code --install-extension esp32-token-display-1.0.0.vsix --force

---

Edit → Rebuild → Reinstall Workflow

cd e:\Gap_code\TokenDisply\vscode-extension

# 1. Edit source files (ConfigPanel.ts, ConfigManager.ts, etc.)

# 2. Package (compiles + bundles + creates .vsix)
npm run package

# 3. Install
code --install-extension esp32-token-display-1.0.0.vsix --force

# 4. In VS Code: Ctrl+Shift+P → "Developer: Reload Window"

Tip: After reload, the Config Panel reopens automatically because activate() calls ConfigPanel.createOrShow().

Tip: When testing board-specific flows, verify both the board selector value and the generated PlatformIO command line in the Actions output.

---

Adding a New Tab

1. Add a tab button in _html() (around line 257–262):

   <button class="tab-btn" data-tab="mytab">🆕 My Tab</button>
   

2. Add the matching pane with id="tab-mytab":

   <div class="tab-pane" id="tab-mytab">
     ...content...
   </div>
   

3. If new fields need saving, add them to ESP32Config interface in ConfigManager.ts, update DEFAULTS, buildConfigH() / buildEnv(), and load().

---

Adding a New VS Code Command

1. Register in package.json → contributes.commands:

   { "command": "esp32td.myCommand", "title": "My Command", "category": "ESP32 Token Display" }
   

2. Wire up in extension.ts:

   vscode.commands.registerCommand('esp32td.myCommand', () => { /* … */ })
   

---

Common Issues

Build/flash runs against wrong board env

• Check Device tab board selection.
• Confirm Actions output starts with pio ... run -e <expected-env>.
• If selection resets after reload, check .vscode/esp32-display.json write permissions.

Port/speed changed in wrong env section

Confirm that save logic is patching only the selected env section in platformio.ini. If keys are missing in that section, add them manually once (upload_port, monitor_port, upload_speed) so future patches can replace values safely.

out/extension.js is stale after editing

Run npm run build (or npm run package to also get a fresh .vsix).

Extension does not activate

• Check the Output panel → ESP32 Token Display channel.
• Make sure "activationEvents": ["onStartupFinished"] is in package.json.
• Verify the installed version with: code --list-extensions --show-versions | Select-String esp32.

Webview shows blank / old content

The webview HTML is inlined as a template string in ConfigPanel._html(). After rebuilding the extension JS, reload VS Code (Developer: Reload Window).

vsce not found

npm install --save-dev @vscode/vsce

TypeScript errors

npm run compile   # shows all tsc errors without bundling