prometeu-studio/docs/studio/agendas/Asset Bank Composition Area - Dual List and Capacity Meter Agenda.md

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
2. base component construction: Agenda-02-Asset-Bank-Composition-Base-Components.md
3. Bank Composition section shell: Agenda-03-Asset-Bank-Composition-Section-Shell.md
4. bank-composition middleware/controller: Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md
5. middleware-driven interaction: Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md
6. persistence: 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.