event bus start: code, PRs e specs

This commit is contained in:
2026-03-24 13:42:43 +00:00
parent a16d63cfb5
commit e7670b5474
16 changed files with 731 additions and 42 deletions
@@ -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`
+11 -2
View File
@@ -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`