prometeu-studio/discussion/workflow/plans/PLN-0071-vscode-dynamic-theme-translation-adapter.md

id	ticket	title	status	created	completed	tags
PLN-0071	frontend-visual-theme-spec-and-css-retirement	VS Code Dynamic Theme Translation Adapter	open	2026-05-06		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.