---
id: LSN-0005
ticket: studio-docs-import
title: Studio events and components legacy lesson
created: 2026-03-26
tags:
  - studio
  - legacy-import
  - events
  - components
---

## Context

Legacy import from `docs/studio/learn/mental-model-studio-events-and-components.md`.

This lesson preserves the Studio-wide mental model for typed events and the `prometeu-studio-components` control layer.

## Key Decisions

### Studio should grow through typed events and a Studio-owned control layer

**What:** The Studio should use a typed event model with both workspace buses and a global bus, automatically republishing workspace events upward, while visible controls should come through `prometeu-studio-components` rather than raw JavaFX usage scattered across the app.
**Why:** Direct references between shell, workspaces, and services create coupling that becomes hard to unwind as the application gains global activity, background operations, multiple workspaces, and cross-cutting actions. Raw JavaFX use also causes naming, styling, and behavior drift.
**Trade-offs:** This approach adds explicit control layers and event publication paths, but it keeps the UI dialect smaller, more opinionated, and easier to evolve consistently.

## Patterns and Algorithms

- Give each workspace its own bus and republish workspace events to the global Studio bus.
- Keep event publication explicit and typed.
- Use `prometeu-studio-components` as the Studio-facing control API rather than reimplementing JavaFX wholesale.
- When adding UI code, ask whether the behavior is an event and whether the control is part of the Studio-visible dialect.

## Pitfalls

- Letting shell, workspaces, and services call each other directly by convenience.
- Spreading raw JavaFX controls directly across the app.
- Recreating local wrappers and styling hooks inconsistently.
- Treating the component layer as a full JavaFX replacement instead of a focused Studio API.

## Takeaways

- Typed events and a Studio-owned control layer solve different problems, but together they prevent architectural drift as the UI grows.
- Workspace-local segregation and global shell visibility both matter; one bus alone is not enough.
- Legacy source attribution: `docs/studio/learn/mental-model-studio-events-and-components.md`.