prometeu-studio/docs/studio/specs/2. Studio UI Foundations Specification.md

Studio UI Foundations Specification

Status: Draft Scope: Naming, event publication model, and Studio UI foundations Purpose: Define the shared infrastructure rules that all Studio UI work must follow.

Authority and Precedence

This specification consolidates the accepted Studio UI foundations decision into normative form.

Normative Inputs

• Studio shell structures
• workspace UI structures
• Studio-owned services
• shell and workspace event publication needs
• reusable Studio control infrastructure

Core Rules

1. Studio UI naming must be explicit by role.
2. The Studio must define its own typed event system.
3. The Studio event system must include one global bus and one bus per workspace.
4. Every event published on a workspace bus must also be published on the global bus automatically.
5. Studio UI must preserve theme and i18n compatibility by construction.

Naming by Role

Studio naming must follow role-oriented conventions.

Baseline naming guidance:

• StudioShell* for shell-level structures;
• *Workspace for workspaces;
• *Panel for composed regions or panels;
• *View for focused visual views;
• *Item or *Row for list and cell-like elements;
• StudioEvent* for event types;
• *Service for operational services;
• *Control for reusable low-level visual controls.

Names must communicate responsibility directly. Vague naming that hides shell, panel, workspace, or control roles is non-conforming.

Studio Event System

The Studio must not rely on stringly-typed event routing as its primary contract.

Baseline event rules:

• event publication is local to the process;
• event publication is strongly typed;
• event payloads are DTOs and should be immutable where practical;
• event publication and subscription management must be thread-safe;
• the baseline model should remain intentionally small;
• a large reactive framework is not baseline behavior.

Thread safety is required because background work such as asset recognition, scanning, diagnostics refresh, or other asynchronous Studio activity may publish events that eventually affect visible UI state.

Global and Workspace Buses

The baseline event topology includes:

• one global StudioEventBus;
• one workspace-local event bus per workspace.

Propagation rules:

• every event published on a workspace bus is automatically republished on the global bus;
• propagation is workspace to global;
• global-to-workspace rebroadcast is not baseline behavior.

This topology exists so callers do not need to duplicate publication decisions manually.

Event Categories

The exact event catalog may evolve incrementally.

Illustrative baseline categories include:

• project lifecycle events;
• project loading lifecycle events;
• workspace selection events;
• run and build intent events;
• activity publication events;
• progress update events;
• diagnostics update events;
• asset selection events.

For project bootstrap and splash/loading integration, the Studio event catalog should reserve typed events for:

• project loading started;
• project loading progress;
• project loading completed;
• project loading failed.

Project loading progress events should carry at least:

• the project identity,
• a typed loading phase,
• a user-facing status message,
• and either determinate progress or an explicit indeterminate marker.

Theme and i18n Compatibility

Shared Studio UI foundations must preserve:

• CSS-based theming;
• locale-safe user-facing text behavior;
• safe runtime locale updates where text changes dynamically;
• no hardcoded user-facing text in reusable Studio controls.

Theme and i18n compatibility are admission requirements for shared UI infrastructure.

Foundation Boundary

Shared Studio foundations include:

• shell-level UI conventions;
• event publication and observation infrastructure;
• reusable Studio control conventions.

Subscription Lifecycle

Reusable Studio controls must have an explicit subscription lifecycle when they observe events or external state.

Baseline rule:

• Studio controls that need event observation should expose subscribe and unsubscribe lifecycle hooks that can be overridden when needed.
• Studio controls should also expose attach and detach lifecycle hooks for integration with the UI tree.
• onAttached() should trigger subscription setup.
• onDetached() should trigger subscription teardown.

This exists to make event wiring visible, testable, and safe under UI lifecycle changes.

The exact base class or interface shape is an implementation concern, but the lifecycle itself is normative.

Shared Studio foundations do not include:

• domain-specific workspace business logic;
• speculative control catalogs;
• unrelated non-visual infrastructure that does not directly serve Studio UI.

Non-Goals

• defining the full event catalog in advance
• defining every future workspace interaction
• defining the first concrete control implementation wave in detail

Exit Criteria

This specification is complete enough when:

• naming rules are stable enough to guide new Studio code;
• the event topology is explicit;
• theme and i18n constraints are unambiguous for shared Studio UI work.