119 lines
5.3 KiB
Markdown
119 lines
5.3 KiB
Markdown
---
|
|
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.
|