vscode-extension-dev

Extension Architecture

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:

Also written by extension:

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

Tab ↔ Pane Map

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