235 lines
12 KiB
Markdown
235 lines
12 KiB
Markdown
# Asset Bank Composition Area - Dual List and Capacity Meter Agenda
|
|
|
|
Status: Open (Umbrella, split into follow-up agendas)
|
|
Domain Owner: `docs/studio`
|
|
Cross-Domain Impact: `docs/packer`
|
|
|
|
## Problem
|
|
|
|
The Studio `Assets` details area does not yet expose an explicit authoring surface for bank composition based on internal asset files.
|
|
|
|
The next planned area is not a simple form row.
|
|
It combines:
|
|
|
|
- a left-side transfer area with `available files` and `files included in build`;
|
|
- a right-side vertical capacity meter for fixed bank size usage;
|
|
- rule-driven gating where files can no longer be moved into the build set once the bank reaches its fixed size limit.
|
|
|
|
This looks small in layout terms, but it hides many interaction details:
|
|
|
|
- which files are shown at all;
|
|
- which files are build-eligible;
|
|
- how diagnostics affect transfer availability;
|
|
- whether order matters;
|
|
- how the meter behaves near or above the limit;
|
|
- and how Studio should explain hard capacity blockers without becoming noisy.
|
|
|
|
This topic needs a Studio agenda before it becomes a decision or implementation PR.
|
|
|
|
## Context
|
|
|
|
Recent packer work now gives the runtime snapshot enough information to support this UI discussion more concretely:
|
|
|
|
- available files per registered asset;
|
|
- build-candidate files derived from the current walk;
|
|
- file-scoped diagnostics kept segregated for future UI use;
|
|
- measured bank size usage for the current build-candidate set;
|
|
- stable asset identity through `asset_id` for registered assets only.
|
|
|
|
That means the Studio can now discuss this area against a real backend shape instead of inventing a purely visual placeholder.
|
|
|
|
Important constraints already known:
|
|
|
|
1. only registered assets should participate in this internal bank-composition flow;
|
|
2. the snapshot should retain file inventory and build-candidate information, but not raw file bytes;
|
|
3. bank size is fixed on the hardware/runtime side;
|
|
4. when the bank reaches its maximum size, the UI must block adding more files into the build set.
|
|
|
|
## Current Code Context
|
|
|
|
The current Studio selected-asset details composition is still centered on:
|
|
|
|
- summary and actions;
|
|
- runtime contract;
|
|
- diagnostics and preview-related surfaces already present in the details flow.
|
|
|
|
Relevant code anchors today:
|
|
|
|
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
|
|
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/contract/AssetDetailsContractControl.java`
|
|
- `docs/studio/specs/4. Assets Workspace Specification.md`
|
|
|
|
There is no existing `DualListView<T>` or dedicated bank-composition control in `prometeu-studio` yet.
|
|
|
|
That matters because this agenda is not only about layout.
|
|
It is about how a new section inside `Asset Details` should behave and how its internal components should coordinate.
|
|
|
|
## Recommendation
|
|
|
|
Create a dedicated `Bank Composition` section inside `Asset Details`, implemented as a `VBox` section just like the other asset-details sections, and explicitly backed by packer runtime data.
|
|
|
|
Operationally, this section should follow the same staged-editing pattern already used by `Runtime Contract`, including `change`, `apply`, `reset`, and `cancel` actions.
|
|
|
|
Recommended baseline shape:
|
|
|
|
1. left side of the section body: a dedicated `StudioDualListView<T>` component with:
|
|
- left list = available files
|
|
- right list = files included in build
|
|
2. right side of the section body: a dedicated vertical `StudioAssetCapacityMeter` component showing current measured usage versus fixed bank capacity
|
|
3. hard gating rule:
|
|
if adding a file would exceed the fixed bank size, the move must be blocked before the item enters the build list
|
|
4. coordination rule:
|
|
the transfer list and the capacity meter must be built as components for this asset-workspace use case and must be able to exchange typed events through the `workspaceBus`
|
|
|
|
Why this direction:
|
|
|
|
- it gives bank composition its own didactic and operational area inside `Asset Details`;
|
|
- it leaves room to discuss many smaller details without destabilizing the rest of selected-asset details;
|
|
- it keeps authoring behavior aligned with the existing `Runtime Contract` section instead of inventing a second editing model inside `Asset Details`;
|
|
- it aligns with the Studio event-driven workspace model already used by the `Assets` workspace.
|
|
|
|
### Component Direction
|
|
|
|
The first implementation should not treat these controls as isolated local widgets.
|
|
|
|
Rules:
|
|
|
|
- `StudioDualListView<T>` is the component name for the transfer-list surface of this section;
|
|
- `StudioDualListView<T>` should be introduced as an abstract Studio component created for this bank-composition section;
|
|
- `StudioDualListView<T>` should leave concrete behavior to subclasses, with capabilities added incrementally as real bank-composition needs appear;
|
|
- `StudioAssetCapacityMeter` is the component name for the vertical capacity meter of this section;
|
|
- `StudioAssetCapacityMeter` should also be introduced as a Studio component created for this bank-composition section;
|
|
- both components must be able to publish and consume typed events through the `workspaceBus`;
|
|
- the event model must allow coordination not only between the transfer list and the capacity meter, but also with surrounding details/workspace components when selection, eligibility, diagnostics, or staged apply behavior evolves;
|
|
- the first event baseline should stay intentionally small:
|
|
increase and decrease capacity updates expressed as percentage in the `0..1` range are enough to start;
|
|
- the initial component scope is still bank-composition-specific, even if later refactoring makes them reusable elsewhere.
|
|
|
|
### Current Baseline Assumptions
|
|
|
|
The following points are now assumed for the current discussion wave:
|
|
|
|
1. `StudioDualListView<T>` is abstract, with concrete subclasses supplying bank-specific behavior over time.
|
|
2. `Bank Composition` is always visible for the current asset families, because the currently active bank-based families are `Tile` and `Sound`.
|
|
3. `available files` come directly from the snapshot projection derived from `walkResult`.
|
|
4. only files without blocking diagnostics may appear in `available files`.
|
|
5. file order in the right list affects build output and must be developer-controlled.
|
|
6. the right list therefore needs ordering support and should surface indices as part of the UI.
|
|
7. capacity computation is family-specific and must not be normalized prematurely into one fake universal formula.
|
|
8. the bank-composition section should receive its data as part of the normal asset-details fetch.
|
|
9. `StudioDualListView<T>` and `StudioAssetCapacityMeter` should both remain intentionally dumb; a bank-composition middleware/controller should own family-specific UI rules and hard-limit orchestration.
|
|
10. if the Studio later needs non-bank-based asset handling, that should be introduced via another bank manager/composition manager rather than by overengineering this first wave.
|
|
11. the section should use the same staged interaction model as `Runtime Contract`, with `change`, `apply`, `reset`, and `cancel`.
|
|
|
|
### Family-Specific Capacity Notes
|
|
|
|
The current bank-capacity semantics already differ by family:
|
|
|
|
- `Tile` banks are matrix-based.
|
|
Example:
|
|
a `256x256` indexed matrix with tiles configured as `32x32` yields `8x8 = 64` tile slots.
|
|
If each selected build file contributes one `32x32` tile, the bank can contain at most `64` selected files.
|
|
- `Sound` banks are byte-budget-based.
|
|
The relevant measure is sample size in bytes, with a fixed bank capacity such as `1 MB`.
|
|
|
|
That means `StudioAssetCapacityMeter` must be driven by bank-family semantics rather than by one simplistic shared percentage algorithm hidden from the user.
|
|
|
|
### Meter Behavior Baseline
|
|
|
|
The current direction for the meter is explicitly game-like:
|
|
|
|
- a vertical progress-bar style meter that rises as the bank fills;
|
|
- green, orange, and red severity bands instead of one neutral fill;
|
|
- a percentage label below the bar;
|
|
- supporting text or hint copy explaining that banks have fixed capacity and must not be exceeded;
|
|
- hint text should also nudge the developer toward splitting or reorganizing the asset when the bank is too full.
|
|
|
|
Initial thresholds:
|
|
|
|
- green below `65%`
|
|
- orange at `>= 65%` or `> 9/16`
|
|
- red at `>= 95%` or `> 14/16`
|
|
|
|
Hard-limit interaction baseline:
|
|
|
|
- the UI should disable only moves from left to right when capacity is exhausted or the candidate item would overflow the bank;
|
|
- moving items from right to left must remain possible;
|
|
- ordering actions on the right list must remain possible;
|
|
- the surface should still explain why add is blocked, instead of silently failing.
|
|
|
|
### Section Workflow Baseline
|
|
|
|
`Bank Composition` should not auto-persist edits while the developer is moving files around.
|
|
|
|
The first-wave workflow should mirror `Runtime Contract`:
|
|
|
|
- `change` enters editable mode;
|
|
- list transfers, ordering, and capacity feedback happen inside the staged draft state;
|
|
- `apply` persists the new composition;
|
|
- `reset` returns the draft to the last persisted state while staying in the editing flow;
|
|
- `cancel` exits editing and discards uncommitted draft changes.
|
|
|
|
This keeps the mental model of `Asset Details` consistent across sections and avoids mixing immediate-write behavior with staged authoring behavior in the same surface.
|
|
|
|
### Ordering Baseline
|
|
|
|
The current first-wave baseline for right-list ordering is:
|
|
|
|
- `move up`
|
|
- `move down`
|
|
- visible indices on the right/build list
|
|
|
|
Drag-and-drop may still be attractive later, but it is not yet required to validate the first wave.
|
|
|
|
## Open Questions
|
|
|
|
1. What exact first-wave event and controller contract should be defined together for the bank-composition flow, since the `workspaceBus` events and the bank-composition middleware/controller should evolve as one design surface?
|
|
2. What exact explanatory text should the section show for tile-bank exhaustion versus sound-bank exhaustion so the user understands the capacity rule, not just the percentage?
|
|
|
|
### Resolved In This Agenda Wave
|
|
|
|
The following points are now closed for the first wave:
|
|
|
|
1. The UI-facing file-row structure should be a dedicated Studio DTO for any bank type.
|
|
2. The first concrete `StudioDualListView<T>` subclass should be asset-details-specific.
|
|
3. The event contract and middleware/controller shape should be designed together incrementally, without premature generalization.
|
|
4. Detailed wording for family-specific explanatory copy can be deferred until the section contract is otherwise ready.
|
|
|
|
## Suggested Next Step
|
|
|
|
Do not implement the area yet.
|
|
|
|
This umbrella agenda is now intentionally split into focused follow-up agendas aligned to the proposed execution order:
|
|
|
|
1. snapshot transfer into details DTOs:
|
|
[`Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md`](./Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md)
|
|
2. base component construction:
|
|
[`Agenda-02-Asset-Bank-Composition-Base-Components.md`](./Agenda-02-Asset-Bank-Composition-Base-Components.md)
|
|
3. `Bank Composition` section shell:
|
|
[`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](./Agenda-03-Asset-Bank-Composition-Section-Shell.md)
|
|
4. bank-composition middleware/controller:
|
|
[`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](./Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
|
|
5. middleware-driven interaction:
|
|
[`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](./Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
|
6. persistence:
|
|
[`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](./Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
|
|
|
### Proposed Execution Order
|
|
|
|
The current proposed implementation order is:
|
|
|
|
1. transfer snapshot state into asset-details DTOs
|
|
2. build the base and concrete UI components
|
|
3. create the `Bank Composition` UI shell with no behavior
|
|
4. introduce the bank-composition middleware/controller and staged DTO flow
|
|
5. wire developer actions through middleware and `workspaceBus`
|
|
6. persist the selected composition back through packer into `asset.json` and the minimal snapshot
|
|
|
|
This sequence is useful not only for implementation, but also for decision slicing:
|
|
|
|
- early decisions can close DTO and section-shape questions first;
|
|
- middle decisions can close middleware and event-orchestration questions;
|
|
- the final decision can close persistence into `asset.json` and minimal snapshot propagation.
|
|
|
|
The next correct step is to work these follow-up agendas in order and derive smaller `decision` records from them instead of trying to close the whole bank-composition architecture in one pass.
|