101 lines
4.9 KiB
Markdown
101 lines
4.9 KiB
Markdown
---
|
|
id: PLN-0071
|
|
ticket: frontend-visual-theme-spec-and-css-retirement
|
|
title: VS Code Dynamic Theme Translation Adapter
|
|
status: open
|
|
created: 2026-05-06
|
|
completed:
|
|
tags: [vscode, extension, lsp, presentation, theming, adapter]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Turn the VS Code extension into a stable adapter that translates frontend-owned visual theme contracts into VS Code-compatible rendering behavior without requiring source edits for routine frontend theme changes.
|
|
|
|
## Background
|
|
|
|
`DEC-0033` explicitly locks that the extension must not become a repository of manually curated frontend theme rules. The extension must translate the contract it receives rather than being edited whenever a frontend changes colors, emphasis, or theme variants.
|
|
|
|
This plan covers the client-side adapter behavior that satisfies that requirement.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Replace hardcoded per-frontend visual theme rules with dynamic or generated translation based on the transported frontend contract.
|
|
- Define the minimum static VS Code contribution surface still required by the platform.
|
|
- Support multi-theme frontend data consumption and active-theme application.
|
|
- Add extension tests or verification coverage around theme translation.
|
|
|
|
### Excluded
|
|
- Compiler-side contract definition.
|
|
- LSP transport definition.
|
|
- Studio rendering behavior.
|
|
|
|
## Non-Goals
|
|
|
|
- Building a general-purpose VS Code theme marketplace artifact.
|
|
- Allowing the extension to become a second authored source of frontend theme truth.
|
|
- Solving unrelated reconnect or transport lifecycle issues beyond what this adapter needs.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Identify the minimal static VS Code contribution surface
|
|
|
|
**What:** Separate what the extension must declare statically from what it can translate dynamically.
|
|
**How:** Keep only the minimal `package.json` contribution data required for VS Code to recognize semantic token kinds or activate the extension. Remove hardcoded frontend-specific color rules from static configuration where dynamic translation can take over.
|
|
**File(s):** `tools/vscode-extension/package.json`, related extension bootstrap files.
|
|
|
|
### Step 2 - Implement contract-to-VS Code theme translation
|
|
|
|
**What:** Translate frontend-owned visual contract data into VS Code-understandable configuration.
|
|
**How:** Update extension runtime code to receive the transported visual theme contract, map token and editor-surface data into the VS Code APIs/configuration model, and apply the active frontend theme deterministically.
|
|
**File(s):** `tools/vscode-extension/src/**`, mirrored build outputs only if local toolchain constraints require temporary manual sync.
|
|
|
|
### Step 3 - Support multi-theme frontends without extension source edits
|
|
|
|
**What:** Make frontend theme growth operationally cheap.
|
|
**How:** Ensure that adding or changing frontend-owned themes does not require new extension source logic unless the VS Code platform itself introduces a new capability boundary. Theme identity, token rules, and active selection must be data-driven.
|
|
**File(s):** `tools/vscode-extension/src/**`, possible supporting protocol model surfaces if consumed directly.
|
|
|
|
### Step 4 - Add adapter verification coverage
|
|
|
|
**What:** Protect the no-manual-theme-maintenance rule.
|
|
**How:** Add tests or deterministic verification around:
|
|
|
|
1. translation of token rules,
|
|
2. translation of editor-surface colors where supported,
|
|
3. handling of multiple frontend themes,
|
|
4. absence of hardcoded PBS-only theme logic in the adapter path.
|
|
|
|
**File(s):** `tools/vscode-extension/src/test/**` if present, or equivalent test harness/verification approach adopted by the extension module.
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- Validate translation of structured token rules into VS Code-compatible theme rules.
|
|
- Validate active-theme switching behavior for data-driven frontend themes.
|
|
|
|
### Integration Tests
|
|
- Run extension-targeted validation proving the frontend contract can change without source-level theme edits.
|
|
|
|
### Manual Verification
|
|
- Open PBS content through the extension and confirm the active theme is applied from transported contract data rather than hardcoded `package.json` color tables.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The extension no longer depends on hardcoded frontend-specific theme rules as the primary rendering source.
|
|
- [ ] Frontend theme changes are driven by contract data rather than extension source edits.
|
|
- [ ] Multi-theme frontend payloads can be translated and applied deterministically.
|
|
- [ ] The remaining static VS Code contribution surface is minimal and structural only.
|
|
|
|
## Dependencies
|
|
|
|
- `DEC-0033` accepted and normatively locked.
|
|
- `PLN-0069` for transport of visual theme data to the extension.
|
|
|
|
## Risks
|
|
|
|
- VS Code platform constraints may force a hybrid static/runtime model that must stay carefully bounded.
|
|
- The current local Node/TypeScript environment issues can slow validation.
|
|
- Leaving too much theme data in `package.json` would preserve the current maintenance problem under a new name.
|