prometeu-studio/docs/specs/studio/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.
6. Lifecycle-managed event subscription is the canonical way Studio controls observe external state.
7. The Studio must provide a reusable workspace framework for event-driven workspace composition.
8. Studio workspaces must consume that framework rather than invent refresh-heavy workspace-local patterns.

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.

The global Studio bus is backed by a typed event bus reference owned by the Studio application container.

Container rules:

• the Studio Container owns the global typed event bus reference used by StudioEventBus;
• host-integrated services that need shared Studio operational visibility should receive that container-owned typed event bus reference during bootstrap instead of allocating disconnected local buses;
• the Container must be initialized during Studio boot before packer-backed integration services, workspaces, or adapters begin use.

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 workspace framework primitives;
• reusable Studio control conventions.

Shared Studio foundations do not, by themselves, define workspace-local feature scope. For example, read-only editor behavior, passive placeholder regions, manual-refresh-only navigator behavior, and similar local workspace rules must be closed by workspace-local specifications rather than inferred from this document alone.

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.

Canonical Workspace Framework

The Studio workspace model is not just a collection of unrelated screens.

Baseline workspace-framework rules are:

• a workspace should be built as a composition root plus lifecycle-managed child controls;
• child controls should subscribe only to the workspace events or external state they actually consume;
• local UI changes should be propagated through typed events and targeted patches where identity is preserved;
• structural synchronization should be explicit and separate from local patch propagation;
• whole-workspace refresh is a structural recovery path, not the default routine interaction path.

The baseline reusable workspace framework should cover at least:

• composition-root conventions;
• lifecycle-managed event-subscriber controls;
• projection-host patterns for list/tree/detail surfaces;
• local-patch versus structural-sync orchestration rules.

When a workspace first wave is intentionally passive or read-only, that workspace may still consume the framework without forcing a premature event or mutation contract.

The first concrete proving ground for this framework may be a single workspace, but the resulting framework is normative for future Studio workspace implementation.

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
• allowing each workspace to define its own incompatible event/lifecycle model

Exit Criteria

This specification is complete enough when:

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