event bus start: code, PRs e specs
This commit is contained in:
@@ -0,0 +1,124 @@
|
||||
# PR-07a Assets Event Topology and Lifecycle Foundation
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Refactor the `Assets` workspace foundation away from a monolithic `AssetWorkspace` that redraws major regions after local changes.
|
||||
|
||||
This slice establishes the corrective architectural direction for the Studio as a whole.
|
||||
|
||||
`Assets` is the first consumer and proving ground, but the target is not an `Assets`-only pattern.
|
||||
|
||||
The Studio-standard direction is:
|
||||
|
||||
- lifecycle-aware UI components;
|
||||
- typed workspace events as the update mechanism;
|
||||
- component-scoped subscriptions;
|
||||
- explicit separation between structural workspace sync and local UI projection updates;
|
||||
- reusable workspace framework pieces that other Studio workspaces must consume instead of inventing their own refresh-heavy flow.
|
||||
|
||||
## Objective
|
||||
|
||||
Create the event-driven workspace foundation required for all later `Assets` refactor slices and establish it as the correct Studio-wide pattern for workspace implementation.
|
||||
|
||||
After this PR:
|
||||
|
||||
- the workspace root coordinates composition instead of owning every region render path;
|
||||
- navigator, row, details, and details-internal controls can subscribe independently;
|
||||
- the workspace event bus becomes the primary update path for UI change propagation;
|
||||
- `refresh()` is no longer the default answer for local state changes.
|
||||
- the extracted lifecycle/event-driven primitives are designed for reuse by non-`Assets` workspaces.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
- existing `StudioWorkspaceEventBus`
|
||||
- existing `StudioControlLifecycle` support
|
||||
|
||||
## Scope
|
||||
|
||||
- define the target event topology for the `Assets` workspace
|
||||
- define the target event topology as the canonical Studio workspace model
|
||||
- split workspace responsibilities between composition, state coordination, and component rendering
|
||||
- extract reusable workspace framework primitives where the abstraction is already justified by the `Assets` refactor
|
||||
- introduce lifecycle-aware component boundaries for:
|
||||
- navigator host
|
||||
- asset-list host
|
||||
- asset-row item
|
||||
- details host
|
||||
- details-local sections/forms
|
||||
- introduce reusable patterns or base components for:
|
||||
- workspace composition roots
|
||||
- lifecycle-managed event subscribers
|
||||
- projection host controls
|
||||
- structural-sync versus local-patch orchestration
|
||||
- define typed events for:
|
||||
- structural snapshot changes
|
||||
- projection changes
|
||||
- selection changes
|
||||
- selected-asset details lifecycle
|
||||
- local patch propagation
|
||||
- demote global redraw events to transitional or removable status
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final navigator visuals redesign in this slice
|
||||
- no final details-panel redesign in this slice
|
||||
- no mutation-semantics redesign beyond event routing needs
|
||||
- no broad shell-level event-system rewrite outside `Assets`
|
||||
- no fake generalization disconnected from concrete `Assets` usage
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the component tree and ownership model.
|
||||
The workspace root should compose controls and services, not render every region inline.
|
||||
|
||||
2. Introduce event contracts for the asset workspace projection model.
|
||||
The baseline contract should distinguish:
|
||||
- structural workspace sync events
|
||||
- navigator projection events
|
||||
- selected-asset details events
|
||||
- per-asset patch events
|
||||
|
||||
3. Convert `AssetWorkspace` into a composition root plus orchestration layer.
|
||||
It may still coordinate service calls, but rendering responsibilities should move into dedicated controls.
|
||||
|
||||
4. Extract reusable workspace-framework pieces while doing the refactor.
|
||||
`Assets` should consume the same primitives that future Studio workspaces are expected to consume.
|
||||
|
||||
5. Require lifecycle installation for event-consuming controls.
|
||||
Every component that subscribes to workspace events must implement `StudioControlLifecycle` and subscribe only while attached to the scene.
|
||||
|
||||
6. Mark the existing redraw-request pattern as transitional.
|
||||
`StudioAssetsNavigatorRedrawRequestedEvent` and `StudioAssetsDetailsRedrawRequestedEvent` should no longer be the target architecture.
|
||||
|
||||
7. Propagate the rule to Studio documentation.
|
||||
The resulting plans/spec updates should make clear that future workspaces are expected to build on this framework instead of introducing workspace-local refresh architecture.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the refactor has a clear component topology instead of one render-heavy workspace class
|
||||
- lifecycle-aware controls own their own subscriptions
|
||||
- the workspace event bus carries typed update events that components can consume independently
|
||||
- local UI changes can be expressed without a full workspace refresh path
|
||||
- the old redraw-request events are either removed or isolated behind temporary compatibility adapters
|
||||
- the extracted primitives are reusable by other Studio workspaces
|
||||
- the plan explicitly establishes this direction as the Studio-standard workspace architecture
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for event routing between composition root and child controls
|
||||
- unit tests for lifecycle subscribe/unsubscribe behavior on workspace controls
|
||||
- smoke validation that mounting and unmounting the workspace does not leak subscriptions
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- new reusable workspace-framework classes under `prometeu-studio/src/main/java/p/studio/...`
|
||||
- new `Assets` workspace controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md`
|
||||
- `docs/studio/specs/3. Studio Components Module Specification.md`
|
||||
- tests for workspace event topology and lifecycle behavior
|
||||
@@ -0,0 +1,75 @@
|
||||
# PR-07b Asset Navigator and Row Subscriptions
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Refactor the navigator side of the `Assets` workspace so the list and each asset row update through event subscriptions instead of workspace-wide rerendering.
|
||||
|
||||
## Objective
|
||||
|
||||
Make navigator behavior event-directed and component-local.
|
||||
|
||||
After this PR:
|
||||
|
||||
- the navigator list subscribes to projection changes it actually needs;
|
||||
- each asset row subscribes to row-scoped summary/selection updates;
|
||||
- search and filters change the navigator projection without rebuilding the whole workspace;
|
||||
- selection styling and row patching happen without forcing a full list refresh from the workspace root.
|
||||
- the navigator and row patterns are implemented in a way that other Studio workspaces can reuse for list/detail navigation surfaces.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- extract the navigator into dedicated controls
|
||||
- separate navigator projection calculation from visual control ownership
|
||||
- introduce row-scoped subscriptions and row identity handling
|
||||
- keep reusable list/projection primitives outside `Assets`-only naming where they are genuinely cross-workspace
|
||||
- publish projection updates for:
|
||||
- search changes
|
||||
- filter changes
|
||||
- structural asset collection changes
|
||||
- per-asset summary patches
|
||||
- selection changes
|
||||
- remove direct row bookkeeping from the workspace root where possible
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no details-panel refactor in this slice
|
||||
- no final mutation confirmation flow refactor in this slice
|
||||
- no broad service-layer redesign beyond what navigator subscriptions require
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce an `AssetNavigatorControl` or equivalent host with lifecycle-managed subscriptions.
|
||||
2. Extract row rendering into an `AssetRowControl` or equivalent lifecycle-managed component.
|
||||
3. Move search/filter handling to event publication plus projection recalculation.
|
||||
4. Publish selection updates as typed events that row controls can consume directly.
|
||||
5. Replace root-owned row maps and manual selection restyling with row-scoped update flow.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- asset rows are no longer rebuilt by default on every local navigator change
|
||||
- search and filter changes update the navigator projection only
|
||||
- selecting an asset updates only the controls that depend on selection
|
||||
- patching one asset summary updates the affected row without requiring a full workspace reload
|
||||
- navigator controls subscribe and unsubscribe through the lifecycle support
|
||||
- reusable navigator/list subscription patterns are left available for future Studio workspaces
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for navigator projection event flow
|
||||
- unit tests for row identity stability across patches
|
||||
- unit tests for selection update behavior without full projection rebuild
|
||||
- UI smoke validation for search, filters, and selection transitions
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- new navigator and row controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- tests for navigator projection and row update behavior
|
||||
@@ -0,0 +1,82 @@
|
||||
# PR-07c Asset Details and Form Lifecycle
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Refactor the selected-asset details side so the details host and its internal sections/forms subscribe only to the state they need.
|
||||
|
||||
This slice explicitly covers the problem called out in the current direction:
|
||||
|
||||
- the selected-asset details host must not own all redraws;
|
||||
- each internal section/form must update from events instead of full details rebuilds.
|
||||
|
||||
## Objective
|
||||
|
||||
Make the details area componentized, lifecycle-aware, and event-driven.
|
||||
|
||||
After this PR:
|
||||
|
||||
- summary/actions, runtime contract, inputs/preview, diagnostics, and mutation-preview sections can update independently;
|
||||
- details load state, ready state, and error state are event-driven;
|
||||
- local form interactions such as preload toggles or preview selection do not rebuild unrelated details content;
|
||||
- internal controls subscribe only while mounted.
|
||||
- the details-section and form-subscription patterns become reusable Studio workspace primitives where appropriate.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
|
||||
- [`./PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- extract the details host into dedicated controls
|
||||
- split details content into lifecycle-aware sections
|
||||
- extract reusable section-host and form-event patterns when they are not asset-specific
|
||||
- define details events for:
|
||||
- details loading started
|
||||
- details ready
|
||||
- details failed
|
||||
- local summary patch applied
|
||||
- preview input changed
|
||||
- preview zoom changed
|
||||
- mutation preview state changed
|
||||
- route details-local form actions through the workspace bus instead of root-owned imperative redraw
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no navigator refactor in this slice
|
||||
- no shell activity redesign in this slice
|
||||
- no cross-workspace form framework extraction unless needed by the `Assets` details controls
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce a dedicated details host control with lifecycle-managed subscriptions.
|
||||
2. Extract stable details sections into separate controls.
|
||||
3. Move details load and error transitions to typed events.
|
||||
4. Route details-local interactions through narrow events and local state holders.
|
||||
5. Remove root-level details reconstruction for interactions that affect only one section.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the selected-asset details view is no longer rebuilt as one large region for section-local changes
|
||||
- forms and preview controls update independently
|
||||
- details-ready and details-error transitions are observable through typed events
|
||||
- details-local subscriptions are owned by the mounted controls, not the workspace root
|
||||
- changing one local control does not force unrelated details sections to rerender
|
||||
- reusable details/form lifecycle patterns are available for future Studio workspaces
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for details lifecycle event flow
|
||||
- unit tests for section-local updates
|
||||
- unit tests for preload-toggle or equivalent form patch behavior
|
||||
- UI smoke validation for selection, details loading, preview interaction, and diagnostics visibility
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- new details controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- tests for details load state and section-local updates
|
||||
@@ -0,0 +1,83 @@
|
||||
# PR-07d Asset Mutation and Structural Sync Orchestration
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Replace the current mutation flow that falls back to `refresh()` after many operations with an event-directed orchestration model.
|
||||
|
||||
The key rule is:
|
||||
|
||||
- local patches stay local;
|
||||
- only structural workspace changes trigger structural sync;
|
||||
- structural sync is explicit and typed, not an incidental rerender path.
|
||||
|
||||
## Objective
|
||||
|
||||
Make asset operations compatible with the event-driven component model.
|
||||
|
||||
After this PR:
|
||||
|
||||
- direct mutations publish patch or structural-sync events according to their actual impact;
|
||||
- row and details controls react to targeted operation results when possible;
|
||||
- create/remove/relocate or other structural operations request a workspace sync explicitly;
|
||||
- the workspace no longer treats every successful operation as a reason to reload everything.
|
||||
- the local-patch versus structural-sync rule is available as a reusable Studio workspace orchestration rule.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`./PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
|
||||
- [`./PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- classify operations by update impact:
|
||||
- local summary patch
|
||||
- details patch
|
||||
- structural workspace sync
|
||||
- failure retention/reporting
|
||||
- extract reusable orchestration helpers or contracts where the distinction is cross-workspace rather than asset-specific
|
||||
- route mutation preview/apply results through typed events
|
||||
- replace generic `refresh()` fallbacks for non-structural success paths
|
||||
- keep progress/log/activity integration aligned with the new orchestration path
|
||||
- make structural sync requests explicit and testable
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no redesign of packer service semantics
|
||||
- no generic Studio-wide command bus abstraction in this slice
|
||||
- no persistence work unrelated to asset-workspace orchestration
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define operation-result events and structural-sync request events.
|
||||
2. Map each mutation action to its update strategy.
|
||||
3. Update mutation flows to publish events instead of directly forcing global workspace refresh.
|
||||
4. Keep structural reload only for actions that truly change collection shape or asset identity.
|
||||
5. Wire progress, logs, and activity to the new operation flow without reintroducing redraw coupling.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- include/exclude, preload, and similar local operations can update via targeted events
|
||||
- create/register/remove/relocate use explicit structural-sync flow only when required
|
||||
- mutation preview and apply flows do not directly rebuild navigator and details by default
|
||||
- activity/log/progress signals remain correct under the new orchestration
|
||||
- the remaining structural sync path is narrow, explicit, and justified by actual data-shape changes
|
||||
- the orchestration rule is documented as reusable Studio behavior, not an `Assets` exception
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for operation-to-update-strategy mapping
|
||||
- unit tests for structural-sync event publication
|
||||
- unit tests for targeted patch propagation after successful operations
|
||||
- UI smoke validation for register/include/exclude/relocate/remove flows
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- mutation and orchestration classes under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- tests for mutation orchestration and structural sync behavior
|
||||
@@ -0,0 +1,74 @@
|
||||
# PR-07e Assets Refactor Cleanup and Regression Coverage
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Consolidate the refactor by removing obsolete redraw-heavy code paths, tightening naming, and locking the event-driven behavior with tests.
|
||||
|
||||
## Objective
|
||||
|
||||
Finish the corrective refactor so the codebase does not drift back toward monolithic render ownership.
|
||||
|
||||
After this PR:
|
||||
|
||||
- obsolete redraw-request and monolithic render helpers are removed;
|
||||
- remaining component boundaries are clearer and easier to maintain;
|
||||
- tests guard lifecycle, event routing, and selective-update behavior;
|
||||
- the workspace code is organized around durable responsibilities rather than incremental leftovers.
|
||||
- the resulting framework is left in a shape that other Studio workspaces can adopt directly.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`./PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`./PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- remove dead or transitional redraw-oriented code
|
||||
- rename classes/events where the old naming reflects the wrong direction
|
||||
- tighten package structure for navigator, details, and orchestration code
|
||||
- make reusable framework pieces visible and discoverable to future workspace implementations
|
||||
- add regression coverage for:
|
||||
- lifecycle subscription hygiene
|
||||
- selection propagation
|
||||
- row patch propagation
|
||||
- details-local updates
|
||||
- structural sync boundaries
|
||||
- update Studio learn/spec material if the refactor exposes terminology drift
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no new user-facing asset features in this slice
|
||||
- no speculative refactor outside the `Assets` workspace and its direct event contracts
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Remove compatibility layers that existed only to bridge from the old refresh-heavy implementation.
|
||||
2. Normalize class and event naming around lifecycle and event-driven ownership.
|
||||
3. Reorganize tests to reflect component boundaries instead of one giant workspace class.
|
||||
4. Update documentation to reflect the stabilized architecture.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the refactored `Assets` workspace no longer depends on redraw-request events as a primary mechanism
|
||||
- code ownership is split along navigator, details, and orchestration boundaries
|
||||
- lifecycle and event-driven behavior are covered by focused tests
|
||||
- the remaining `AssetWorkspace` root is materially smaller and primarily compositional
|
||||
- the reusable framework surface is clear enough for other workspaces to consume instead of cloning `Assets` internals
|
||||
|
||||
## Validation
|
||||
|
||||
- full unit-test pass for asset-workspace packages
|
||||
- targeted regression tests for mount/unmount lifecycle safety
|
||||
- targeted regression tests proving that local updates stay local unless structural sync is requested
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/...`
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md`
|
||||
- `docs/studio/learn/mental-model-assets-workspace.md`
|
||||
@@ -43,8 +43,17 @@ The current Studio execution queue is:
|
||||
3. [`PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
|
||||
4. [`PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
|
||||
5. [`PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
6. [`PR-06-project-scoped-studio-state-and-activity-persistence.md`](./PR-06-project-scoped-studio-state-and-activity-persistence.md)
|
||||
6. [`PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
7. [`PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md)
|
||||
8. [`PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
9. [`PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md)
|
||||
10. [`PR-07e-assets-refactor-cleanup-and-regression-coverage.md`](./PR-07e-assets-refactor-cleanup-and-regression-coverage.md)
|
||||
11. [`PR-06-project-scoped-studio-state-and-activity-persistence.md`](./PR-06-project-scoped-studio-state-and-activity-persistence.md)
|
||||
|
||||
The `PR-07` family is a corrective refactor pass for the current `Assets` implementation.
|
||||
It exists to replace the refresh-heavy direction with lifecycle-managed, event-driven ownership.
|
||||
It also establishes the intended Studio-wide workspace framework, with `Assets` as the first consumer and proof point.
|
||||
|
||||
Recommended execution order:
|
||||
|
||||
`PR-05a -> PR-05b -> PR-05c -> PR-05d -> PR-05e -> PR-06`
|
||||
`PR-05a -> PR-05b -> PR-05c -> PR-05d -> PR-05e -> PR-07a -> PR-07b -> PR-07c -> PR-07d -> PR-07e -> PR-06`
|
||||
|
||||
Reference in New Issue
Block a user