diff --git a/docs/studio/pull-requests/PR-01-studio-event-bus-foundation.md b/docs/studio/pull-requests/PR-01-studio-event-bus-foundation.md index c2e3dcc4..bc6d1ca7 100644 --- a/docs/studio/pull-requests/PR-01-studio-event-bus-foundation.md +++ b/docs/studio/pull-requests/PR-01-studio-event-bus-foundation.md @@ -11,9 +11,19 @@ This PR introduces the generic `StudioEventBus` foundation that later Studio cod - workspace-to-global propagation, - project launcher and shell interactions. +The implementation should be based conceptually on the C# event system located at: + +`/Users/niltonconstantino/personal/workspace.personal/unity/My-Local-Packages/Packages/intrepid-general-utilities/Runtime/SimpleEvents` + +The generic bus machinery should live in shared infrastructure, not in the Studio components module. + +The bus must be thread-safe because background work such as asset recognition, tree refresh triggers, diagnostics updates, and other asynchronous Studio tasks may publish events from outside the UI thread. + ## Objective -Implement the typed Studio event infrastructure in application code so future Studio work can publish and observe events without string routing or ad hoc direct coupling. +Implement the typed Studio event infrastructure so future Studio work can publish and observe events without string routing or ad hoc direct coupling. + +The generic event bus core should be introduced in `prometeu-infra`, while Studio-specific bus composition remains in Studio code. ## Dependencies @@ -22,7 +32,8 @@ Implement the typed Studio event infrastructure in application code so future St ## Scope -- introduce a generic typed `StudioEventBus` +- introduce a generic typed event bus foundation in `prometeu-infra` +- introduce Studio-specific global and workspace bus composition on top of that foundation - introduce a workspace-local bus model - support automatic workspace-to-global propagation - introduce DTO-style event payload contracts @@ -35,37 +46,48 @@ Implement the typed Studio event infrastructure in application code so future St - integrating the full packer event lane now - redesigning the whole shell in this PR - moving visual controls into `prometeu-studio-components` +- placing the generic bus core inside `prometeu-studio-components` ## Execution Method -1. Introduce a small event contract in `prometeu-studio`. -2. Use typed DTO events, preferably immutable. -3. Make subscription and unsubscription explicit and safe. -4. Implement one global bus and one workspace bus type. -5. Ensure every workspace event is automatically republished to the global bus. -6. Keep propagation one-way: workspace to global. -7. Add tests for: +1. Use `/Users/niltonconstantino/personal/workspace.personal/unity/My-Local-Packages/Packages/intrepid-general-utilities/Runtime/SimpleEvents` as the architectural reference point. +2. Port the useful baseline ideas into Java rather than copying Unity-specific structure literally. +3. Introduce the generic event bus machinery in `prometeu-infra`. +4. Keep the generic layer unaware of Studio shell semantics. +5. Introduce the Studio-specific event contract and bus composition above that generic layer. +6. Use typed DTO events, preferably immutable. +7. Make subscription and unsubscription explicit and safe. +8. Implement one global bus and one workspace bus type for Studio. +9. Ensure every workspace event is automatically republished to the global bus. +10. Keep propagation one-way: workspace to global. +11. Make publication and subscription management thread-safe. +12. Add tests for: - typed subscription - unsubscription - workspace-to-global propagation - no accidental global-to-workspace rebroadcast + - concurrent publication and subscription safety ## Acceptance Criteria -- `prometeu-studio` has a generic typed `StudioEventBus` +- `prometeu-infra` has a generic typed event bus foundation +- Studio code has a global and workspace bus composition built on top of that foundation - workspace buses exist and can be attached to the global bus - every workspace-published event is observable on the global bus - callers do not need to publish the same event twice manually - event payloads are DTO-style and not string-based +- publication and subscription handling are safe under concurrent access - automated tests cover the propagation baseline ## Validation - unit tests for bus behavior - basic smoke coverage for publish/subscribe and nested propagation +- concurrent test coverage for thread-safe event publication ## Affected Artifacts +- `prometeu-infra` - `prometeu-studio` application infrastructure - future shell integration points - tests for Studio UI foundation code diff --git a/docs/studio/pull-requests/PR-02-studio-shell-components-wave-1.md b/docs/studio/pull-requests/PR-02-studio-shell-components-wave-1.md index 5d6a12c4..b58b3ed5 100644 --- a/docs/studio/pull-requests/PR-02-studio-shell-components-wave-1.md +++ b/docs/studio/pull-requests/PR-02-studio-shell-components-wave-1.md @@ -43,14 +43,18 @@ Initial candidate controls: 2. Keep each control API small and Studio-facing. 3. Keep styling themeable through CSS. 4. Keep user-facing text bindable and locale-safe. -5. Refactor the shell layer in `prometeu-studio` to consume these controls instead of raw JavaFX where the controls are now available. -6. Avoid adding speculative controls with no immediate shell use. +5. Establish explicit `subscribe()` and `unsubscribe()` lifecycle hooks in the control layer so event-driven controls can override them when needed. +6. Establish `onAttached()` and `onDetached()` hooks that call `subscribe()` and `unsubscribe()` respectively. +7. Refactor the shell layer in `prometeu-studio` to consume these controls instead of raw JavaFX where the controls are now available. +8. Avoid adding speculative controls with no immediate shell use. ## Acceptance Criteria - the first shell-facing controls exist in `prometeu-studio-components` - those controls are used by the Studio shell code - no new shell control work lands directly on raw JavaFX when a Studio control is now available +- event-driven controls have explicit subscribe and unsubscribe lifecycle hooks +- attach and detach lifecycle hooks drive subscription setup and teardown - theme and i18n compatibility are preserved ## Validation diff --git a/docs/studio/specs/2. Studio UI Foundations Specification.md b/docs/studio/specs/2. Studio UI Foundations Specification.md index a72cd0c4..865825f0 100644 --- a/docs/studio/specs/2. Studio UI Foundations Specification.md +++ b/docs/studio/specs/2. Studio UI Foundations Specification.md @@ -51,9 +51,12 @@ 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: @@ -102,6 +105,21 @@ Shared Studio foundations include: - 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; diff --git a/docs/studio/specs/3. Studio Components Module Specification.md b/docs/studio/specs/3. Studio Components Module Specification.md index 65da1aef..74a74c46 100644 --- a/docs/studio/specs/3. Studio Components Module Specification.md +++ b/docs/studio/specs/3. Studio Components Module Specification.md @@ -66,6 +66,21 @@ Rules: - exhaustive mirroring of upstream JavaFX APIs is not required; - the goal is consistency and clarity, not a perfect one-to-one mirror of every JavaFX type. +## Control Lifecycle Hooks + +Studio controls may need to observe event buses or other external state. + +Rules: + +- the control layer must provide explicit subscribe and unsubscribe lifecycle methods that can be overridden when needed; +- the control layer should also provide `onAttached()` and `onDetached()` lifecycle hooks; +- `onAttached()` should call `subscribe()`; +- `onDetached()` should call `unsubscribe()`; +- controls that attach subscriptions must also define how those subscriptions are released; +- event-driven controls must not hide subscription lifecycle completely inside ad hoc local wiring. + +These hooks exist so event-driven controls remain predictable and safe to embed in shell and workspace UI. + ## Typical Control Scope Typical controls that belong in the module include: