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
@@ -0,0 +1,84 @@
---
id: LSN-0049
discussion: DSC-0031
title: Remove the embedded editor stack before rebuilding code workflows
status: done
created: 2026-05-08
updated: 2026-05-08
tags: [studio, editor, cleanup, lsp, vfs, shell, migration]
---
## Original Problem
Studio still carried an embedded `Code Editor` workspace together with a `prometeu-vfs` boundary and a legacy `prometeu-lsp` path that existed only to support that editor.
That stack had become architectural drag:
- the JavaFX editor was no longer a product direction;
- the legacy `VFS` and `LSP` contracts were shaped around that editor model;
- shell state and project session still persisted editor-specific assumptions;
- and keeping those surfaces alive made any future code-backend redesign harder.
## Consolidated Decision
`DEC-0031` locked a full cleanup of the embedded editor stack.
The repository removed:
- the `Code Editor` workspace as an active Studio surface;
- the legacy editor-owned `VFS` boundary;
- the legacy editor-era `LSP` assumptions;
- shell/session/state dependencies that expected the editor to exist;
- and normative references that treated that stack as current architecture.
The decision also locked an equally important limit:
- this cleanup was not allowed to define the future code backend;
- a replacement LSP or automation boundary had to come later, in separate discussion.
## Final Result
The Studio shell now opens with surviving workspaces only: `Assets`, `Debug`, and `Shipper`.
Project-local state no longer persists editor restoration or editor layout fields, while still loading old state safely and falling back to surviving shell behavior.
The cleanup also succeeded without freezing the repository in a "no LSP ever again" state.
Later work in `DSC-0032` introduced a new project-scoped LSP boundary as separate architecture, which is exactly what `DEC-0031` required: remove the old stack first, then rebuild cleanly under a new decision.
## Implementation Notes
The cleanup landed in three coordinated waves:
1. shell/session/state cleanup removed `WorkspaceId.EDITOR`, editor restoration state, and editor-owned session composition;
2. the old editor-era `VFS` and `LSP` stack stopped being the active Studio foundation;
3. specs, tests, and historical references were revised so the removed editor stack no longer appears as current product guidance.
This produced an important boundary reset:
- Studio remains responsible for launcher, assets, shipper, debug, build, and run orchestration;
- code-editing architecture is no longer smuggled in through dead UI or legacy session seams.
## Example
Before the cleanup, an old `.studio/state.json` could still restore editor-centric state.
After the cleanup, the same persisted payload is treated defensively:
- old editor fields are ignored;
- the selected workspace falls back safely when `EDITOR` is present;
- the project reopens into a surviving workspace instead of reviving a dead surface.
## Pitfalls and Anti-Patterns
- Do not preserve dead editor-era boundaries "for compatibility" when the product direction has already moved.
- Do not treat naming continuity as architectural continuity. A later `prometeu-lsp` module can be valid if it comes from a new discussion and a new boundary.
- Do not leave project-local state as an accidental migration trap; persisted legacy fields must degrade safely.
## References
- `AGD-0034` Limpeza completa do Workspace Editor do Studio e remoção dos acoplamentos legados
- `DEC-0031` Limpeza completa do Workspace Editor do Studio e remoção dos acoplamentos legados
- `PLN-0062` Shell Session and State Cleanup After Editor Removal
- `PLN-0063` Legacy LSP and VFS Module Removal with Runtime Preservation
- `PLN-0064` Normative Test and Lesson Cleanup for Editor Stack Removal
- `LSN-0047` Project-scoped LSP boundary and protocol containment
@@ -0,0 +1,93 @@
---
id: LSN-0050
discussion: DSC-0033
title: Frontend-owned visual themes with structured contract and host adapters
status: done
created: 2026-05-08
updated: 2026-05-08
tags: [compiler, compiler-general, frontend, presentation, theming, lsp, vscode, pbs]
---
## Original Problem
Frontend semantic presentation was frontend-owned in principle, but not in a form that could survive multiple hosts.
PBS still depended on authored semantic CSS as the practical visual source of truth, which created three problems:
- CSS was a host-facing artifact rather than a compiler-general contract;
- VS Code could only approximate frontend intent through manual translation;
- every host risked drifting away from the frontend's real visual identity.
## Consolidated Decision
`DEC-0033` replaced authored host-consumed semantic CSS with a structured frontend-owned visual contract.
That contract now owns:
- the frontend theme list;
- the default active theme;
- token-scoped styles;
- editor-surface palette data;
- and host projections used to translate frontend semantic keys into host-native semantic selectors.
Hosts are adapters over this data.
They do not own frontend visual truth.
## Final Result
The canonical visual source now lives in `FrontendSemanticPresentationSpec`, with concrete PBS theme data and host projections authored in structured Java models instead of CSS resources.
The new LSP path transports:
- frontend semantic keys;
- visual themes;
- active theme identity;
- and host projection metadata.
The VS Code extension consumes that payload and writes semantic token and workbench color customizations dynamically, which means routine frontend color changes no longer require hand-edited extension theme tables.
The old PBS semantic CSS still exists only as migration residue and derivative compatibility material.
It is no longer the authored canonical contract.
## Implementation Notes
The decision was realized across four layers:
1. compiler/frontend metadata grew a structured presentation contract;
2. PBS migrated its theme definition into that contract;
3. the LSP description path started exporting visual themes and host projections;
4. the VS Code extension became a mechanical translator of the contract at runtime.
This also clarified the relationship between `DSC-0033` and `DSC-0034`:
- `DSC-0033` established the structured theme contract and CSS retirement;
- `DSC-0034` established that host projections belong in the frontend contract rather than in the host.
Together they define the current highlight pipeline.
## Example
For PBS today:
- the frontend publishes semantic keys such as `pbs-keyword` and `pbs-service`;
- the same frontend publishes the canonical theme colors and emphasis flags for those keys;
- the LSP sends the theme plus a `vscode` host projection;
- the VS Code extension applies both the canonical semantic selectors and the projected host selectors.
This is why a color change in PBS theme data can flow to VS Code without a new curated palette in `package.json`.
## Pitfalls and Anti-Patterns
- Do not reintroduce CSS as a silent second source of truth.
- Do not move frontend theme authorship into host adapters just because one host has capability gaps.
- Do not collapse frontend semantic identity into generic host categories during transport; host categories are projections, not the canonical vocabulary.
## References
- `AGD-0036` Frontend Visual Theme Spec and Retirement of Host-Consumed Semantic CSS
- `DEC-0033` Frontend-owned visual theme spec as canonical presentation contract
- `PLN-0068` Frontend Visual Contract and PBS Migration
- `PLN-0069` LSP Visual Theme Transport and Theme Selection Propagation
- `PLN-0070` Studio Visual Theme Adapter and CSS Retirement
- `PLN-0071` VS Code Dynamic Theme Translation Adapter
- `LSN-0048` Frontend-owned semantic vocabularies with declarative host projection