Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/workflow/plans/PLN-0068-frontend-visual-contract-and-pbs-migration.md

5.3 KiB
Raw Blame History

id ticket title status created completed tags
PLN-0068 frontend-visual-theme-spec-and-css-retirement Frontend Visual Contract and PBS Migration open 2026-05-06
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.