housekeeping

This commit is contained in:
2026-05-08 09:17:43 +01:00
parent 0e6a2cd5bc
commit ef814b2420
16 changed files with 215 additions and 1274 deletions
@@ -1,91 +0,0 @@
---
id: PLN-0062
ticket: studio-editor-workspace-cleanup
title: Shell Session and State Cleanup After Editor Removal
status: done
created: 2026-05-05
completed: 2026-05-05
tags: [studio, editor, cleanup, shell, session, state]
---
## Objective
Remove the `Code Editor` workspace from the Studio shell and reconfigure project session and persisted state so the application remains coherent without any editor-owned concepts.
## Background
`DEC-0031` locks the complete removal of the embedded editor stack. The shell, project session, workspace registry, and `.studio/state.json` currently still assume the existence of `WorkspaceId.EDITOR`, `EditorWorkspace`, editor restoration state, and editor-specific layout state.
## Scope
### Included
- Remove `WorkspaceId.EDITOR` from the Studio shell.
- Remove `EditorWorkspace` registration and shell integration.
- Remove editor-specific state persistence and restoration paths.
- Remove `LSP`/`VFS` legacy ownership from `StudioProjectSession` and `StudioProjectSessionFactory`.
- Keep `Assets`, `Shipper`, `Debug`, launcher, and shell flows functional.
### Excluded
- Removal of the `prometeu-lsp` and `prometeu-vfs` module source trees themselves.
- Documentation and lesson cleanup.
- New code backend or replacement LSP architecture.
## Execution Steps
### Step 1 - Remove editor workspace registration from the shell
**What:** Remove all shell-level references to the `Code Editor` workspace.
**How:** Update the main window composition to stop creating `EditorWorkspace`, remove the editor rail item, stop selecting or restoring `WorkspaceId.EDITOR`, and ensure shell fallback remains stable when old persisted state still references the editor.
**File(s):** `prometeu-studio/src/main/java/p/studio/window/MainView.java`, `prometeu-studio/src/main/java/p/studio/workspaces/WorkspaceId.java`, any directly related shell controls or selectors.
### Step 2 - Remove editor-owned state and restoration from project-local state
**What:** Remove editor layout and restoration data from persisted project-local Studio state.
**How:** Simplify `ProjectLocalStudioState` to remove `editorRestoration` and `shellLayout.editorLayout`, update normalization/defaults, and make loading old `.studio/state.json` degrade safely without crashes or stale editor assumptions.
**File(s):** `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioState.java`, `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioStateService.java`, any callers that write or restore editor state.
### Step 3 - Reconfigure project session to stop owning editor legacy dependencies
**What:** Remove legacy editor-driven `LSP` and `VFS` ownership from project session composition.
**How:** Refactor `StudioProjectSession` and `StudioProjectSessionFactory` so opening a project no longer constructs `VfsProjectDocument` or `LspService`, and so close semantics remain valid without those resources.
**File(s):** `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java`, `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSessionFactory.java`, dependent tests.
### Step 4 - Remove bootstrap/container dependencies that only existed for the editor stack
**What:** Remove application bootstrap and container seams that exist only to inject legacy editor stack services.
**How:** Delete `LspServiceFactory` and `ProjectDocumentVfsFactory` accessors from the container surfaces once shell/session no longer depend on them, and update `AppContainer` accordingly.
**File(s):** `prometeu-studio/src/main/java/p/studio/Container.java`, `prometeu-app/src/main/java/p/studio/AppContainer.java`, directly affected tests.
## Test Requirements
### Unit Tests
- Update session and state tests to reflect the absence of editor state.
- Add coverage for loading old persisted project-local state without editor restoration fields being required.
### Integration Tests
- Verify the main Studio shell opens a project and activates a surviving workspace without editor registration.
- Verify session close still saves valid project-local state and shuts down surviving services cleanly.
### Manual Verification
- Open the Studio shell and confirm only surviving workspaces appear.
- Reopen a project with stale `.studio/state.json` containing editor data and confirm safe fallback.
- Confirm project switching and shell startup remain stable.
## Acceptance Criteria
- [x] `WorkspaceId.EDITOR` no longer exists in production code.
- [x] `MainView` no longer instantiates or restores `EditorWorkspace`.
- [x] Project-local state no longer persists editor restoration or editor layout fields.
- [x] `StudioProjectSession` no longer owns legacy editor `LSP`/`VFS` resources.
- [x] The Studio shell remains functional with surviving workspaces.
## Dependencies
- `DEC-0031` accepted and normatively locked.
- Knowledge of all shell/session/state call sites that currently assume the editor exists.
## Risks
- Shell restoration may break if old persisted state is not normalized defensively.
- Session teardown may regress if hidden resource ownership remains after field removal.
- Removing editor assumptions too early may temporarily orphan callers still using editor-specific state APIs.
@@ -1,91 +0,0 @@
---
id: PLN-0063
ticket: studio-editor-workspace-cleanup
title: Legacy LSP and VFS Module Removal with Runtime Preservation
status: done
created: 2026-05-05
completed: 2026-05-05
tags: [studio, editor, cleanup, lsp, vfs, runtime]
---
## Objective
Remove the legacy `prometeu-lsp` and `prometeu-vfs` modules and all remaining code references to them while preserving compiler, shipper, play, run, and debug flows that do not depend on the editor stack.
## Background
`DEC-0031` treats the current `prometeu-lsp` and `prometeu-vfs` modules as part of the embedded editor legacy stack. The Studio execution path must continue to compile, build, package, and run projects through the existing compiler and runtime orchestration layers.
## Scope
### Included
- Remove `prometeu-lsp` modules from Gradle settings and codebase references.
- Remove `prometeu-vfs` modules from Gradle settings and codebase references.
- Remove tests dedicated to these legacy modules.
- Verify `StudioShipperService`, `StudioPlayStopCoordinator`, and runtime/debug flows remain intact.
### Excluded
- Shell/editor state cleanup handled by a separate plan.
- Documentation/spec/lesson cleanup handled by a separate plan.
- New replacement backend services.
## Execution Steps
### Step 1 - Remove Gradle module registration for legacy editor stack modules
**What:** Stop building the legacy `prometeu-lsp` and `prometeu-vfs` modules.
**How:** Remove the module includes and any direct module dependencies that point to `prometeu-lsp:*` and `prometeu-vfs:*`, then fix resulting build graph fallout in Studio modules.
**File(s):** `settings.gradle.kts`, affected `build.gradle.kts` files in `prometeu-app`, `prometeu-studio`, and module directories.
### Step 2 - Remove legacy module source trees and direct test coverage
**What:** Delete the legacy `prometeu-lsp` and `prometeu-vfs` code once all consumers are detached.
**How:** Remove module source files and their dedicated tests only after production call sites no longer compile against them.
**File(s):** `prometeu-lsp/**`, `prometeu-vfs/**`, related test sources in `prometeu-studio`.
### Step 3 - Preserve compiler and shipper build flow
**What:** Ensure build preparation still uses the canonical compiler pipeline without editor legacy dependencies.
**How:** Validate and adjust `StudioShipperService` and any shipper/build callers so they continue using `BuilderPipelineService`, `BuilderPipelineConfig`, and `BuilderPipelineContext` directly without reintroducing removed editor-layer seams.
**File(s):** `prometeu-studio/src/main/java/p/studio/shipper/StudioShipperService.java`, affected compiler/shipper integration tests.
### Step 4 - Preserve play, run, and debug execution flow
**What:** Ensure runtime orchestration continues to function after legacy module removal.
**How:** Re-test and patch `StudioPlayStopCoordinator`, runtime handshake services, execution session handling, and debug workspace projections if any hidden import or event dependency pointed at removed editor-stack modules.
**File(s):** `prometeu-studio/src/main/java/p/studio/execution/StudioPlayStopCoordinator.java`, `prometeu-studio/src/main/java/p/studio/debug/runtime/**`, `prometeu-studio/src/main/java/p/studio/workspaces/debug/**`, related tests.
## Test Requirements
### Unit Tests
- Update or remove module-specific tests for `prometeu-lsp` and `prometeu-vfs`.
- Preserve unit coverage for execution session, play/stop coordination, and runtime handshake behavior.
### Integration Tests
- Run compiler pipeline integration tests that cover `analyze`, `compile`, and `build`.
- Run shipper/build integration tests that exercise `StudioShipperService`.
- Run runtime/debug integration or coordinator tests that validate play/stop behavior.
### Manual Verification
- Trigger Studio build flow and confirm artifact generation still works.
- Trigger Studio play flow and confirm runtime launch/stop still works.
- Open Debug and Shipper workspaces and confirm they remain operational.
## Acceptance Criteria
- [x] `prometeu-lsp` is no longer part of the build graph.
- [x] `prometeu-vfs` is no longer part of the build graph.
- [x] No production Studio class imports legacy `LSP` or `VFS` module types.
- [x] Compiler and shipper build flows still work.
- [x] Play/run/debug flows still work without the removed modules.
## Dependencies
- `DEC-0031` accepted and normatively locked.
- Shell/session cleanup completed enough that no surviving production code still requires legacy `LSP`/`VFS` types.
## Risks
- Hidden transitive dependencies may keep the build graph coupled to removed modules longer than expected.
- Runtime or debug flows may have indirect event or session assumptions not obvious from imports alone.
- Deleting modules too early may obscure compile errors that should instead be fixed in surviving Studio code first.
@@ -1,90 +0,0 @@
---
id: PLN-0064
ticket: studio-editor-workspace-cleanup
title: Normative Test and Lesson Cleanup for Editor Stack Removal
status: done
created: 2026-05-05
completed: 2026-05-05
tags: [studio, editor, cleanup, docs, tests, lessons]
---
## Objective
Remove or revise the normative documentation, tests, lessons, and user-facing resources that describe the embedded editor stack as a current Studio surface.
## Background
`DEC-0031` treats the editor stack removal as both code cleanup and normative cleanup. The repository currently contains active specs, README entries, i18n resources, and lessons that define `Code Editor`, `prometeu-vfs`, and the integrated semantic-read phase as active architecture.
## Scope
### Included
- Remove or rewrite Studio specs dedicated to the embedded editor stack.
- Update the Studio specs index and README.
- Remove or archive editor/LSP/VFS-specific tests that are no longer valid.
- Reclassify legacy lessons and references so they are not presented as active guidance.
- Remove user-facing i18n strings that only existed for the editor stack.
### Excluded
- Implementation of shell/session/module cleanup itself.
- Future specs for the replacement backend or replacement external-editor strategy.
## Execution Steps
### Step 1 - Clean normative Studio specs
**What:** Remove or replace specs that define the embedded editor stack as active architecture.
**How:** Delete or explicitly retire the `Code Editor`, `Project Document VFS`, and `Integrated LSP Semantic Read Phase` specs, then rewrite any remaining Studio README/index material so it no longer points to dead architecture.
**File(s):** `docs/specs/studio/5. Code Editor Workspace Specification.md`, `docs/specs/studio/6. Project Document VFS Specification.md`, `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`, `docs/specs/studio/README.md`.
### Step 2 - Clean user-facing resources and shell references
**What:** Remove editor-specific strings, labels, and messages that no longer correspond to product surfaces.
**How:** Delete `workspace.code` and `codeEditor.*` message keys and any equivalent theme or resource references still tied to removed editor UI.
**File(s):** `prometeu-studio/src/main/resources/i18n/messages.properties`, any directly related theme or resource files.
### Step 3 - Clean tests and update surviving expectations
**What:** Remove tests whose sole purpose was validating the editor stack and update remaining tests to stop expecting that stack.
**How:** Delete or rewrite tests for editor workspace behavior, legacy `LSP`, legacy `VFS`, session expectations, and any shell assertions that still require the editor workspace.
**File(s):** `prometeu-studio/src/test/java/p/studio/projectsessions/**`, editor-related tests, `prometeu-lsp/**/test/**`, `prometeu-vfs/**/test/**`, any shell-level tests affected by workspace removal.
### Step 4 - Reclassify lessons and historical references
**What:** Ensure discussion lessons remain historically useful without being mistaken for current architecture.
**How:** Review the lessons and references tied to editor/VFS/LSP waves and either archive them, mark them as legacy, or update index/readme material so they are not treated as active operational guidance.
**File(s):** affected files under `discussion/lessons/DSC-0010*`, `DSC-0012*`, `DSC-0013*`, `DSC-0014*`, `DSC-0016*`, `DSC-0017*`, `DSC-0020*`, `DSC-0021*`, plus any summary/index surfaces that present them.
## Test Requirements
### Unit Tests
- Ensure no surviving test suite still references removed editor stack types or message keys.
- Add assertions where needed that remaining shell/resource state is internally consistent.
### Integration Tests
- Validate the Studio docs/spec tree remains internally linked after removal or retirement of the editor specs.
- Validate the build/test graph no longer includes editor-stack-only suites.
### Manual Verification
- Read the Studio spec README and confirm it no longer advertises the removed stack as active.
- Inspect project lessons/readme surfaces and confirm editor-stack lessons are clearly historical or retired.
- Launch the application and confirm no missing i18n keys or dead UI labels remain.
## Acceptance Criteria
- [x] Studio specs no longer define the embedded editor stack as an active surface.
- [x] Studio README/index material no longer points to removed editor/VFS/LSP architecture as current.
- [x] Editor-specific i18n keys are removed or no longer consumed.
- [x] Obsolete tests are removed or rewritten.
- [x] Historical lessons are clearly demoted from active operational guidance.
## Dependencies
- `DEC-0031` accepted and normatively locked.
- Sufficient implementation progress that the codebase no longer depends on the removed specs/resources/tests.
## Risks
- Removing normative docs too early may temporarily leave the repo without clear current guidance.
- Historical lessons may still be valuable; deleting them outright could lose context that should instead be reclassified.
- Partial cleanup can leave broken links or missing i18n keys that only appear at runtime.
@@ -1,118 +0,0 @@
---
id: PLN-0068
ticket: frontend-visual-theme-spec-and-css-retirement
title: Frontend Visual Contract and PBS Migration
status: open
created: 2026-05-06
completed:
tags: [compiler, compiler-general, frontend, pbs, presentation, theming, contract]
---
## Objective
Introduce the canonical structured frontend visual contract in `FrontendSpec`, migrate PBS to that contract, and demote `semantic-highlighting.css` from authored truth to migration-only input.
## Background
`DEC-0033` locks that frontend visual intent must become structured canonical data, support multiple themes per frontend, remain token-centric, and retire authored host-consumed semantic CSS as the canonical source.
PBS is the first frontend and therefore defines the first concrete migration path, but the contract MUST remain compiler-general rather than PBS-shaped by accident.
## Scope
### Included
- Evolve compiler/frontend metadata to publish a structured visual contract.
- Define the contract shape for semantic-token styling, editor surfaces, and theme identity.
- Migrate PBS to the new contract.
- Preserve any temporary migration utility needed to derive the first contract from the existing PBS CSS.
- Add validation tests that make the new contract normative and stable.
### Excluded
- LSP transport changes.
- Studio rendering changes.
- VS Code runtime translation changes.
## Non-Goals
- Designing a generic host-owned theme engine.
- Supporting every possible frontend visual attribute in wave 1.
- Keeping authored CSS as a parallel canonical source.
## Execution Steps
### Step 1 - Define the structured visual contract in compiler-general surfaces
**What:** Replace the resource-centric semantic presentation shape with a canonical structured visual contract in `FrontendSpec`.
**How:** Add or evolve frontend metadata models so each frontend can publish:
1. semantic token vocabulary ownership,
2. one or more named visual themes,
3. token-centric visual rules,
4. editor-surface colors needed to preserve frontend identity.
The model MUST be compiler-general and MUST NOT encode PBS-specific assumptions into the shared type system.
**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/models/**`, affected frontend registry/definition surfaces.
### Step 2 - Define the theme and token rule semantics explicitly
**What:** Make the contract operational rather than descriptive.
**How:** Specify exact fields, invariants, and null/empty behavior for:
1. theme identity,
2. theme selection metadata if needed at the contract layer,
3. token style rules,
4. editor surface colors,
5. versioning semantics inside or alongside `FrontendSpec`.
The implementation MUST make it possible for hosts to translate the contract mechanically without inferring missing meaning.
**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/**`, associated tests in compiler modules.
### Step 3 - Migrate PBS from authored CSS truth to structured contract truth
**What:** Make PBS the first frontend to author the new contract.
**How:** Update `PBSDefinitions` and related PBS presentation metadata to publish one or more frontend-owned themes through the new contract. The existing `semantic-highlighting.css` MAY be parsed or manually transcribed to bootstrap the migration, but once the structured contract is in place, CSS MUST no longer be treated as authored truth.
**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**`, `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/themes/pbs/**`, related PBS tests.
### Step 4 - Lock contract validity with tests
**What:** Prevent future drift back to opaque resource ownership.
**How:** Add tests that assert:
1. frontends publish structured visual themes,
2. PBS token vocabulary and theme definitions are coherent,
3. required token styles and editor-surface data resolve correctly,
4. authored CSS is no longer the canonical contract source.
**File(s):** compiler-general and PBS test suites.
## Test Requirements
### Unit Tests
- Validate model invariants for theme IDs, token rules, and editor-surface fields.
- Validate `FrontendSpec` copies and exposes structured theme data safely.
- Validate PBS publishes at least one coherent theme using the new contract.
### Integration Tests
- Run targeted compiler and PBS tests proving the contract compiles, resolves, and remains discoverable through frontend definitions.
### Manual Verification
- Inspect the PBS frontend definition and confirm the structured contract is the readable authored source of truth.
- Confirm any remaining CSS is clearly migration-only or generated-output-only.
## Acceptance Criteria
- [ ] `FrontendSpec` publishes a structured canonical visual contract.
- [ ] The contract supports multiple themes per frontend.
- [ ] The contract is token-centric and can also express editor-surface colors.
- [ ] PBS is migrated to the new contract.
- [ ] `semantic-highlighting.css` is no longer treated as authored canonical frontend presentation data.
## Dependencies
- `DEC-0033` accepted and normatively locked.
## Risks
- Overfitting the first contract to PBS would weaken future frontend adoption.
- An underspecified token-style model would force host inference and violate the decision.
- Keeping CSS alive as a silent parallel truth source would nullify the migration.
@@ -1,114 +0,0 @@
---
id: PLN-0069
ticket: frontend-visual-theme-spec-and-css-retirement
title: LSP Visual Theme Transport and Theme Selection Propagation
status: open
created: 2026-05-06
completed:
tags: [studio, lsp, protocol, transport, presentation, theming, compiler]
---
## Objective
Extend the LSP boundary and transport surfaces so hosts receive frontend-owned visual theme data, theme identity, and active-theme information without collapsing that contract into host-authored categories.
## Background
`DEC-0033` requires LSP to transport enough structured frontend-owned visual information for hosts to render the active frontend theme, preserve frontend and token identity, and avoid forcing the extension to keep hand-maintained theme rules.
The compiler contract itself is handled by `PLN-0068`. This plan covers the transport boundary that carries that contract into host adapters.
## Scope
### Included
- Extend internal LSP-facing description or capability surfaces to expose structured frontend visual contract data.
- Transport theme identity and active-theme information where needed.
- Preserve semantic token identity and frontend ownership through mapping layers.
- Add transport-level tests for the new visual contract payloads.
### Excluded
- Defining the compiler-general contract itself.
- Studio-side rendering implementation.
- VS Code-side rendering implementation.
## Non-Goals
- Inventing host-owned fallback theme categories.
- Expanding LSP beyond what is required to carry the visual contract.
- Building transport that requires hand-curated per-frontend extension updates.
## Execution Steps
### Step 1 - Extend internal LSP descriptions to carry visual contract data
**What:** Evolve the LSP-side server/bridge description surfaces to expose frontend-owned visual contract data instead of ad hoc token metadata only.
**How:** Update `lsp-api` and `lsp-v1` internal description models so they can carry:
1. frontend identity,
2. semantic token legend identity,
3. available theme definitions or references,
4. active theme selection.
The payload shape MUST remain faithful to the frontend contract and MUST NOT normalize it into host-owned abstractions.
**File(s):** `prometeu-lsp/prometeu-lsp-api/src/main/java/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`.
### Step 2 - Thread the visual contract through bridge and mapper layers
**What:** Ensure the compiler-backed bridge and protocol mappers preserve visual theme data end to end.
**How:** Update bridge services, protocol mappers, server description responses, and any capability/bootstrap path that currently exposes token data so they now expose the structured visual contract and active theme metadata.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/**`, `.../messages/**`, `.../mapping/**`.
### Step 3 - Define theme selection behavior for host consumption
**What:** Make active-theme semantics operational.
**How:** Define and implement the transport rule for which theme a host should apply:
1. single-theme frontend behavior,
2. multi-theme frontend behavior,
3. default theme behavior when no host override is in play,
4. how active-theme selection is surfaced to adapters.
The transport MUST make host behavior deterministic without host-owned guessing.
**File(s):** `prometeu-lsp/prometeu-lsp-api/**`, `prometeu-lsp/prometeu-lsp-v1/**`, tests.
### Step 4 - Add transport conformance tests
**What:** Prevent regression back to token-only or host-shaped payloads.
**How:** Add tests that verify:
1. theme payloads are present,
2. token identities survive transport unchanged,
3. active-theme information is deterministic,
4. no mapper collapses frontend-owned visual data into host-authored categories.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`, `prometeu-lsp/prometeu-lsp-api/src/test/java/**` if needed.
## Test Requirements
### Unit Tests
- Validate DTO/model invariants for theme payloads and active-theme fields.
- Validate mapper behavior for full visual contract transport.
### Integration Tests
- Run targeted LSP tests proving a compiler-backed frontend description reaches the host adapter layer with visual theme data intact.
### Manual Verification
- Inspect initialize/description pathways and confirm theme metadata is present and frontend-shaped.
## Acceptance Criteria
- [ ] LSP description/transport surfaces carry structured frontend visual theme data.
- [ ] Theme identity and active-theme semantics are deterministic.
- [ ] Semantic token identity remains frontend-owned end to end.
- [ ] No LSP layer introduces host-owned theme abstractions as canonical transport data.
## Dependencies
- `DEC-0033` accepted and normatively locked.
- `PLN-0068` for the compiler-side contract shape and PBS migration.
## Risks
- Transporting too little theme data would force host inference and violate the decision.
- Transporting host-shaped payloads would silently recreate the wrong ownership boundary.
- Theme selection semantics can become ambiguous unless explicitly defined in this plan.
@@ -1,101 +0,0 @@
---
id: PLN-0070
ticket: frontend-visual-theme-spec-and-css-retirement
title: Studio Visual Theme Adapter and CSS Retirement
status: open
created: 2026-05-06
completed:
tags: [studio, editor, presentation, theming, adapter, css-retirement]
---
## Objective
Make Studio consume the structured frontend visual contract as an adapter, remove any remaining dependency on authored frontend semantic CSS as the canonical source, and keep any host rendering mechanism clearly derivative.
## Background
`DEC-0033` locks that Studio is a rendering adapter over frontend-owned visual themes and that generated CSS is acceptable only as an adapter mechanism, not as the canonical frontend artifact.
This plan applies that rule to the Studio side of the stack.
## Scope
### Included
- Update Studio-side presentation registries or rendering services to consume structured frontend visual contract data.
- Generate or map host rendering artifacts from the structured contract if Studio still needs CSS or equivalent host render descriptors.
- Remove reliance on authored frontend semantic CSS as a direct semantic presentation contract.
- Add Studio tests proving the adapter path is derivative and deterministic.
### Excluded
- Compiler-side contract design.
- LSP transport contract design.
- VS Code adapter behavior.
## Non-Goals
- Rebuilding the deleted legacy Studio editor stack.
- Introducing Studio-owned frontend themes.
- Preserving authored semantic CSS as a parallel truth source.
## Execution Steps
### Step 1 - Update Studio presentation consumption to use the structured contract
**What:** Make Studio consume frontend-owned visual theme data instead of resource-only semantic presentation.
**How:** Update presentation registries, semantic highlighting services, or other editor-related rendering seams so they resolve structured visual theme data from the frontend description path.
**File(s):** `prometeu-studio/src/main/java/**`, any remaining editor/presentation adapter surfaces still active after cleanup.
### Step 2 - Derive host rendering artifacts from the contract
**What:** Keep Studio rendering mechanical.
**How:** If Studio still requires CSS or CSS-like structures, generate or map them from the structured frontend visual contract. The host-generated artifact MUST be clearly derivative and MUST NOT be treated as authored frontend truth.
**File(s):** `prometeu-studio/src/main/java/**`, possible theme/presentation helper modules, generated resource paths if adopted.
### Step 3 - Remove direct canonical dependence on frontend semantic CSS
**What:** Retire the old consumption model.
**How:** Remove or rewrite any code path that treats frontend semantic CSS resources as the canonical semantic presentation input. Leave only temporary compatibility or generated-output behavior if strictly needed during rollout.
**File(s):** `prometeu-studio/**`, related frontend resource loading code.
### Step 4 - Add Studio adapter conformance tests
**What:** Lock the adapter boundary.
**How:** Add tests that verify:
1. Studio consumes structured frontend visual themes,
2. token style rendering inputs are contract-derived,
3. any generated CSS is derivative,
4. Studio does not silently fall back to host-authored frontend theme logic.
**File(s):** `prometeu-studio/src/test/java/**` and any relevant integration test modules.
## Test Requirements
### Unit Tests
- Validate contract-to-rendering translation logic.
- Validate theme selection consumption on the Studio side.
### Integration Tests
- Run targeted Studio-side tests proving frontend presentation resolves from structured contract data and not from authored semantic CSS.
### Manual Verification
- Inspect the Studio path and confirm remaining CSS, if any, is generated or compatibility-only.
## Acceptance Criteria
- [ ] Studio consumes structured frontend visual contract data.
- [ ] Any Studio-side CSS or equivalent rendering descriptor is derivative, not canonical.
- [ ] Direct canonical dependence on authored frontend semantic CSS is removed.
- [ ] Studio does not reauthor frontend visual identity locally.
## Dependencies
- `DEC-0033` accepted and normatively locked.
- `PLN-0068` for the canonical compiler/frontend contract.
- `PLN-0069` for transport of visual contract data into the host boundary.
## Risks
- Studio may still hide old CSS assumptions in helper layers unless the migration is exhaustive.
- Generated CSS can accidentally become the new silent truth source if ownership boundaries are not explicit in code and tests.
- Residual editor cleanup from earlier refactors may obscure the remaining active consumption path.
@@ -1,100 +0,0 @@
---
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.