clean up
This commit is contained in:
-80
@@ -1,80 +0,0 @@
|
||||
# Asset Bank Composition Snapshot Transfer to Details DTOs Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
The `Bank Composition` section needs a stable details-facing data shape before any component or middleware work can proceed.
|
||||
|
||||
Today the underlying information comes from two different sources:
|
||||
|
||||
- snapshot state derived from `walkResult`, which should feed `available` files;
|
||||
- `asset.json`, which should feed the currently `selected` files for build composition.
|
||||
|
||||
This agenda exists to close how those sources should be transferred into Studio-facing DTOs for `Asset Details`.
|
||||
|
||||
## Context
|
||||
|
||||
Recent packer/runtime work already gives the Studio enough source information to populate a first-wave `Bank Composition` section:
|
||||
|
||||
- registered assets have stable identity;
|
||||
- the snapshot already contains file inventory derived from `walkResult`;
|
||||
- blocking diagnostics already exclude files from being generally available;
|
||||
- selection state is persisted in `asset.json` and is expected to move through the newer `artifacts` shape.
|
||||
|
||||
The Studio should not bind raw UI code directly to packer internals.
|
||||
The section needs a dedicated Studio DTO layer.
|
||||
|
||||
## Options
|
||||
|
||||
1. Bind the UI directly to snapshot and manifest shapes.
|
||||
2. Build one dedicated Studio bank-file DTO for both `available` and `selected` rows.
|
||||
3. Build separate DTOs for `available` rows and `selected` rows.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Direct binding is fast initially but couples Studio too tightly to packer/runtime structures.
|
||||
2. One shared DTO keeps the section simpler and is easier to use across transfer list, meter, and staged draft state.
|
||||
3. Separate DTOs may model source differences more explicitly, but they add mapping and coordination overhead early.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adopt one dedicated Studio DTO family for bank composition rows and section state.
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- `walkResult`-derived snapshot rows become `available`;
|
||||
- `asset.json` composition state becomes `selected`;
|
||||
- both are projected into Studio-owned DTOs before reaching the section UI;
|
||||
- the DTO should be generic enough to work for any bank type, even if family-specific fields arrive later.
|
||||
- the DTO field set should stay intentionally small and grow only when a concrete UI need appears.
|
||||
|
||||
### First-Wave DTO Baseline
|
||||
|
||||
The first-wave DTO direction is intentionally pragmatic:
|
||||
|
||||
- define one Studio-owned bank-file DTO family for both `available` and `selected` rows;
|
||||
- add fields incrementally as real section behavior requires them;
|
||||
- do not project blocking files into the UI DTO layer at all;
|
||||
- keep selected-file order visual in the UI, but persist it in `asset.json` through an explicit index shape such as `{ file, index }`.
|
||||
- start with this minimum first-wave field set:
|
||||
`fileId/path`, `displayName`, `size`, `lastModified`, `fingerprint`, and `metadata`.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. The DTO field set should start small and grow only as concrete UI needs appear.
|
||||
2. Only non-blocking files become `available` DTOs; blocking files should not be projected into the section DTO layer.
|
||||
3. UI ordering is visual, while persisted ordering in `asset.json` should use an explicit index representation such as `{ file, index }`.
|
||||
4. The first DTO revision should start with `fileId/path`, `displayName`, `size`, `lastModified`, `fingerprint`, and `metadata`.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that closes the first-wave Studio DTO shape for `Bank Composition` details data.
|
||||
@@ -1,87 +0,0 @@
|
||||
# Asset Bank Composition Base Components Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
The `Bank Composition` section depends on two new Studio components:
|
||||
|
||||
- `StudioDualListView<T>`
|
||||
- `StudioAssetCapacityMeter`
|
||||
|
||||
Those components need a first-wave contract and scope before the section shell or middleware can be implemented safely.
|
||||
|
||||
## Context
|
||||
|
||||
The current direction is already partially fixed:
|
||||
|
||||
- `StudioDualListView<T>` should be abstract;
|
||||
- the first concrete subclass should be asset-details-specific;
|
||||
- right-list ordering must support `move up`, `move down`, and visible indices;
|
||||
- `StudioAssetCapacityMeter` should be a vertical, game-like progress bar with color bands and percentage text;
|
||||
- both components should stay intentionally dumb and leave family-specific rules to middleware/controller logic.
|
||||
|
||||
## Options
|
||||
|
||||
1. Build highly generic reusable components from the start.
|
||||
2. Build bank-composition-scoped Studio components with narrow first-wave APIs.
|
||||
3. Skip dedicated components and build the section directly inside `AssetDetails`.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Highly generic components risk overengineering before the first section is proven.
|
||||
2. Narrow first-wave components keep momentum and preserve room to generalize later from real usage.
|
||||
3. Inline section code would move faster once, but it would bury behavior that already deserves named UI building blocks.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Build dedicated first-wave components with narrow APIs:
|
||||
|
||||
- abstract `StudioDualListView<T>` as the transfer-list base;
|
||||
- one asset-details concrete subclass first;
|
||||
- `StudioAssetCapacityMeter` as a dumb vertical meter component with color thresholds and percentage display.
|
||||
|
||||
Do not force broad reuse rules yet.
|
||||
|
||||
### First-Wave Component Baseline
|
||||
|
||||
The first-wave component contract should stay intentionally small.
|
||||
|
||||
`StudioDualListView<T>` should expose only the hooks needed for the initial bank-composition section:
|
||||
|
||||
- row text and/or row graphic projection;
|
||||
- current left and right collections;
|
||||
- current selection state;
|
||||
- move left-to-right;
|
||||
- move right-to-left;
|
||||
- `moveUp`;
|
||||
- `moveDown`;
|
||||
- visible index refresh for the right-side list.
|
||||
|
||||
The first concrete asset-details subclass should render rows directly.
|
||||
Do not introduce a separate row renderer abstraction yet.
|
||||
|
||||
`StudioAssetCapacityMeter` should start as a dumb visual component with these baseline inputs:
|
||||
|
||||
- `progress` in the `0..1` range;
|
||||
- a label, including percentage text when needed;
|
||||
- a severity band state;
|
||||
- optional hint text.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. `StudioDualListView<T>` should expose only a narrow first-wave hook set for row projection, selection, transfers, reordering, and right-list index refresh.
|
||||
2. The first concrete asset-details subclass should own row rendering directly.
|
||||
3. `StudioAssetCapacityMeter` should start with `progress`, label, severity band state, and optional hint text.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that fixes the first-wave component contracts for `StudioDualListView<T>` and `StudioAssetCapacityMeter`.
|
||||
@@ -1,77 +0,0 @@
|
||||
# Asset Bank Composition Section Shell Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
`Bank Composition` needs a section shell inside `Asset Details` before behavior is added.
|
||||
|
||||
That shell must align visually and operationally with existing sections, especially `Runtime Contract`, instead of inventing a separate layout and editing model.
|
||||
|
||||
## Context
|
||||
|
||||
The current baseline is already known:
|
||||
|
||||
- `Bank Composition` is a `VBox` section like the others;
|
||||
- it is always visible for the current bank-based families;
|
||||
- it should follow the same staged-editing model as `Runtime Contract`;
|
||||
- the section body should place the dual list on the left and the capacity meter on the right.
|
||||
|
||||
This agenda focuses on the static shell and section composition, not the internal behavior.
|
||||
|
||||
## Options
|
||||
|
||||
1. Add the section only when behavior is ready.
|
||||
2. Build the section shell first, with placeholder or disabled behavior.
|
||||
3. Hide the section behind an experimental flag.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Waiting for full behavior keeps the surface hidden longer and delays visual integration feedback.
|
||||
2. A shell-first approach lets the Studio validate section rhythm, spacing, controls, and staged-edit affordances early.
|
||||
3. A flag adds operational complexity without much value if the section is already part of the near-term plan.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Create the `Bank Composition` section shell early, with no real behavior yet.
|
||||
|
||||
Baseline expectations:
|
||||
|
||||
- section header and actions align with `Runtime Contract`;
|
||||
- `change`, `apply`, `reset`, and `cancel` are part of the shell contract;
|
||||
- body layout already reserves the dual-list and meter regions;
|
||||
- the shell may render with placeholder or disabled internals until middleware arrives.
|
||||
|
||||
### First-Wave Shell Baseline
|
||||
|
||||
The first-wave shell should mirror `Runtime Contract` as closely as practical at the JavaFX composition level.
|
||||
|
||||
That includes:
|
||||
|
||||
- the same section rhythm and action placement model;
|
||||
- the same staged-edit shell expectations;
|
||||
- alignment with the existing `FormSession` pattern instead of inventing a separate section lifecycle.
|
||||
|
||||
Before middleware wiring is ready, the body should render in a disabled or read-only state rather than as an empty placeholder.
|
||||
|
||||
Outside `change` mode, the section should show the current persisted state as read-only.
|
||||
It should not stay visually neutral or look absent when data already exists.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. The section shell should mirror `Runtime Contract` as closely as practical at the JavaFX composition level.
|
||||
2. The shell should align with the existing `FormSession` model for staged editing.
|
||||
3. Before middleware is ready, the body should render disabled or read-only internals instead of an empty placeholder.
|
||||
4. Outside `change` mode, the section should render the current persisted state as read-only.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that fixes the shell contract and static layout of the `Bank Composition` section.
|
||||
@@ -1,92 +0,0 @@
|
||||
# Asset Bank Composition Middleware and Staged Editing Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
`StudioDualListView<T>` and `StudioAssetCapacityMeter` are intentionally dumb.
|
||||
That means `Bank Composition` needs a middleware/controller layer that owns:
|
||||
|
||||
- family-specific capacity rules;
|
||||
- staged draft state;
|
||||
- `change` / `apply` / `reset` / `cancel` orchestration;
|
||||
- hard-limit decisions about whether a candidate file can enter the selected list.
|
||||
|
||||
Without that layer, component responsibilities will blur quickly.
|
||||
|
||||
## Context
|
||||
|
||||
The current direction already rejects two extremes:
|
||||
|
||||
- no component should hide bank-family rules internally;
|
||||
- the first wave should not overgeneralize into a universal bank manager abstraction.
|
||||
|
||||
The middleware/controller therefore needs to be explicit, scoped to `Asset Details`, and designed to evolve incrementally.
|
||||
|
||||
## Options
|
||||
|
||||
1. Put orchestration inside the section control itself.
|
||||
2. Create a dedicated bank-composition middleware/controller for the section.
|
||||
3. Push family-specific logic down into the transfer list and meter components.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Section-local orchestration reduces file count initially, but risks turning `AssetDetails` into a heavy behavior host.
|
||||
2. A dedicated middleware/controller keeps the section and components simpler while preserving room for bank-family policies.
|
||||
3. Embedding rules into components breaks the current design goal of keeping them dumb and composable.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Create a dedicated bank-composition middleware/controller for the section.
|
||||
|
||||
Baseline expectations:
|
||||
|
||||
- own the draft state while editing is active;
|
||||
- translate persisted state into editable state on `change`;
|
||||
- support `reset` back to the persisted state;
|
||||
- support `cancel` by discarding draft changes;
|
||||
- keep `apply` stubbed or disabled until persistence is wired;
|
||||
- delegate family-specific capacity logic through narrowly scoped policies instead of premature platform-wide abstractions.
|
||||
|
||||
### First-Wave Middleware Baseline
|
||||
|
||||
The first wave should not introduce a second session model parallel to the one already used by Studio.
|
||||
|
||||
The middleware/controller should be built around `StudioFormSession<BankCompositionDraft>` as the common staged-edit core.
|
||||
|
||||
Family-specific variation should not come from subclassing `StudioFormSession`.
|
||||
It should come from family-specific draft factories and policies that operate on a shared session model.
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- `StudioFormSession<BankCompositionDraft>` owns `source`, `draft`, `mode`, `isDirty`, `beginEdit`, `reset`, `cancel`, and `apply`;
|
||||
- the bank-composition middleware/controller coordinates that form session for the section;
|
||||
- each asset family can offer its own draft-construction and bank-composition policy implementation;
|
||||
- those policies should decide transfer eligibility, reorder effects, capacity usage, and hard-limit blockers;
|
||||
- `apply` may remain stubbed or disabled until persistence is wired, but the session contract should already be complete.
|
||||
|
||||
The minimal state published by the middleware/controller should be one section-facing view model carrying:
|
||||
|
||||
- shell state such as `isEditing`, `isDirty`, and action availability;
|
||||
- left and right list state;
|
||||
- capacity-meter state;
|
||||
- active blockers and hint messages when relevant.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. The middleware/controller should be built around `StudioFormSession<BankCompositionDraft>`, not a parallel staged-edit model.
|
||||
2. Family-specific behavior should come from draft factories and policies, not from subclassing `StudioFormSession`.
|
||||
3. Family-specific rules should be represented first as small policies offered per asset family.
|
||||
4. The middleware/controller should publish one section-facing view model with shell state, list state, meter state, blockers, and hints.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that fixes the middleware/controller contract and staged-edit lifecycle for the first wave.
|
||||
@@ -1,94 +0,0 @@
|
||||
# Asset Bank Composition WorkspaceBus Interaction Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
The `Bank Composition` section should use `workspaceBus` for coordination, but the first-wave event contract should stay small and be designed together with the middleware/controller.
|
||||
|
||||
This agenda exists to close the first minimal event surface without inventing an oversized bus protocol too early.
|
||||
|
||||
## Context
|
||||
|
||||
The current baseline is already known:
|
||||
|
||||
- events and middleware should evolve together;
|
||||
- the first event baseline can stay very small;
|
||||
- capacity changes are naturally expressed as percentage deltas or level changes in the `0..1` range;
|
||||
- the transfer list and meter should be consumers of orchestrated state, not independent sources of product rules.
|
||||
|
||||
## Options
|
||||
|
||||
1. Define a broad event taxonomy upfront.
|
||||
2. Define only the minimum events needed for the first staged-edit interaction loop.
|
||||
3. Avoid `workspaceBus` and wire components directly.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. A broad taxonomy is easy to regret and hard to prune once code lands.
|
||||
2. A minimal contract matches the current incremental direction and keeps future changes cheap.
|
||||
3. Direct wiring would fight the current workspace architecture and reduce observability of section state changes.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Define a minimal first-wave `workspaceBus` contract together with the middleware/controller.
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- begin with the smallest useful set of section-local events;
|
||||
- include capacity increase/decrease semantics in the `0..1` range only as needed;
|
||||
- avoid encoding family-specific product rules directly into bus event types.
|
||||
|
||||
### First-Wave Event Baseline
|
||||
|
||||
The first wave should keep user actions local to the middleware/controller whenever possible.
|
||||
|
||||
That means the following actions do not need to become public `workspaceBus` commands in the first implementation:
|
||||
|
||||
- `beginEdit`
|
||||
- `moveToSelected`
|
||||
- `moveToAvailable`
|
||||
- `moveUp`
|
||||
- `moveDown`
|
||||
- `reset`
|
||||
- `cancel`
|
||||
- `apply`
|
||||
|
||||
The middleware/controller should receive those actions locally, recalculate section state, and publish only the state transitions or lifecycle notifications that matter outside the section.
|
||||
|
||||
The first public `workspaceBus` notifications should stay minimal:
|
||||
|
||||
- `BankCompositionDraftChanged`
|
||||
- `BankCompositionCapacityChanged`
|
||||
- `BankCompositionApplyRequested`
|
||||
- `BankCompositionApplied`
|
||||
- `BankCompositionApplyFailed`
|
||||
|
||||
Capacity notifications should use absolute progress in the `0..1` range rather than deltas.
|
||||
|
||||
A practical first-wave shape for capacity notifications is:
|
||||
|
||||
- `progress`
|
||||
- `severity`
|
||||
- `blocked`
|
||||
|
||||
If internal increase/decrease semantics are useful later, they can remain local implementation detail rather than part of the initial public bus contract.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. First-wave user actions should stay local to the middleware/controller rather than becoming public bus commands.
|
||||
2. The first public `workspaceBus` contract should be notification-oriented.
|
||||
3. Capacity notifications should use absolute `0..1` progress rather than deltas.
|
||||
4. A minimal first-wave bus surface is enough: draft change, capacity change, apply requested, apply success, and apply failure.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that fixes the minimal first-wave `workspaceBus` contract for `Bank Composition`.
|
||||
-98
@@ -1,98 +0,0 @@
|
||||
# Asset Bank Composition Persistence and Snapshot Propagation Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
When the developer clicks `apply`, the selected files for bank composition must be persisted and reflected back into runtime state.
|
||||
|
||||
That write path spans Studio and packer concerns:
|
||||
|
||||
- staged selected files must be serialized into `asset.json`;
|
||||
- the older `inputsByRole` shape should give way to the newer `artifacts` shape;
|
||||
- the minimal runtime snapshot must reflect the persisted result after apply.
|
||||
|
||||
## Context
|
||||
|
||||
The earlier agendas in this sequence assume `apply` may remain disabled or stubbed until persistence is ready.
|
||||
This agenda isolates the write-path discussion so the rest of the UI can progress first.
|
||||
|
||||
The current direction is already mostly known:
|
||||
|
||||
- persistence should happen through packer, not by having Studio write manifest files directly;
|
||||
- selected composition should be stored in `asset.json`;
|
||||
- runtime state should be refreshed after persistence so `Asset Details` stays coherent.
|
||||
|
||||
## Options
|
||||
|
||||
1. Let Studio write `asset.json` directly.
|
||||
2. Route `apply` through packer services and let packer own manifest persistence plus snapshot refresh.
|
||||
3. Persist only to runtime state first and defer manifest persistence.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Direct manifest writes from Studio would bypass packer ownership and create duplicate write rules.
|
||||
2. A packer-owned write path is cleaner and aligns with existing asset mutation flows.
|
||||
3. Runtime-only persistence would create an unstable editing model and almost certainly drift from disk state.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Route `apply` through packer and persist selected files into `asset.json` using the newer `artifacts` representation.
|
||||
|
||||
Baseline expectations:
|
||||
|
||||
- `apply` submits the selected ordered files to packer;
|
||||
- packer updates `asset.json`;
|
||||
- packer propagates the resulting minimal state back into the runtime snapshot;
|
||||
- Studio refreshes the section from the updated details/snapshot state instead of trusting stale draft data.
|
||||
|
||||
### Persistence Baseline
|
||||
|
||||
The first-wave persistence direction is:
|
||||
|
||||
- `artifacts` replaces the older `inputsByRole` representation in `asset.json`;
|
||||
- the bank-composition selection should therefore persist through `artifacts`, not through a parallel legacy shape;
|
||||
- selected file order should remain explicit in persisted data rather than relying on array position alone.
|
||||
|
||||
### Apply Refresh and Failure Baseline
|
||||
|
||||
After `apply`, the Studio should not trust stale draft state.
|
||||
|
||||
The first-wave refresh baseline is:
|
||||
|
||||
- packer persists the selected ordered files into `asset.json`;
|
||||
- packer refreshes the minimal runtime snapshot state needed by `Asset Details`;
|
||||
- the Studio rebinds the section from the refreshed persisted state and returns the section to consistent read-only mode.
|
||||
|
||||
The minimum refreshed state should include:
|
||||
|
||||
- persisted `selected` rows;
|
||||
- the current `available` projection for details;
|
||||
- recalculated capacity state;
|
||||
- recalculated blockers or eligibility state relevant to the section.
|
||||
|
||||
If `apply` fails:
|
||||
|
||||
- the draft must not be discarded;
|
||||
- the section must remain in editing mode;
|
||||
- the middleware/controller should publish `BankCompositionApplyFailed`;
|
||||
- the UI should show a local error or hint surface;
|
||||
- the user should still be able to retry, reset, or cancel.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. `artifacts` should replace the older `inputsByRole` shape rather than coexist with it for bank-composition persistence.
|
||||
2. After `apply`, packer should refresh the minimal snapshot state required by `Asset Details` and Studio should rebind from that refreshed persisted state.
|
||||
3. If `apply` fails, the draft remains intact, the section stays in editing mode, and the UI surfaces a local failure state while preserving retry, reset, and cancel.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a cross-domain `decision` or a paired `docs/studio` + `docs/packer` decision set that closes the apply write path.
|
||||
-234
@@ -1,234 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,282 +0,0 @@
|
||||
# Pack Wizard in Assets Workspace Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
O workspace `Assets` já reserva a action area para `Pack`, mas ainda não existe uma discussão fechada sobre o fluxo exato desse comando no Studio.
|
||||
|
||||
O pedido atual não é apenas adicionar um botão.
|
||||
O `Pack` precisa abrir um modal que funcione como wizard operacional do empacotador e deixe claro:
|
||||
|
||||
- o resumo do que será empacotado;
|
||||
- a validação obrigatória antes do build;
|
||||
- a regra de bloqueio quando existirem diagnostics em assets incluídos;
|
||||
- o progresso da geração do artefato;
|
||||
- e o resumo final do resultado.
|
||||
|
||||
Sem essa agenda, há risco de misturar decisão de UX com semântica de packer e de implementar um modal visualmente correto, mas operacionalmente fraco.
|
||||
|
||||
## Context
|
||||
|
||||
O estado atual já sugere várias restrições importantes:
|
||||
|
||||
1. o `Assets` workspace define `Pack` como ação global de workspace, não como ação do asset selecionado;
|
||||
2. a spec do Studio já separa `Pack` do fluxo de staged mutations sensíveis;
|
||||
3. a spec do packer define `assets.pa` como artefato runtime autoritativo, com `asset_table` determinística e baseada apenas nos assets incluídos no build set atual;
|
||||
4. o packer já trata diagnostics como parte do modelo operacional, então o Studio não deve inventar uma semântica paralela de validação;
|
||||
5. o usuário precisa de feedback de progresso e de falha com drill-down por asset, não apenas logs.
|
||||
|
||||
Boundary baseline desta agenda:
|
||||
|
||||
- o Studio é casca operacional;
|
||||
- o Studio chama serviços do packer, observa progresso e apresenta estado;
|
||||
- o trabalho bruto de summary, validation, packing e result pertence ao packer;
|
||||
- o Studio não deve reimplementar regras de build, gating ou ordenação.
|
||||
|
||||
Artefatos e referências já relevantes:
|
||||
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md`
|
||||
- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
||||
- `docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md`
|
||||
|
||||
Nota de nomenclatura:
|
||||
|
||||
- a spec vigente usa `assets.pa` como nome canônico do artefato;
|
||||
- esta agenda deve seguir `assets.pa`, mesmo que a conversa operacional use `asset.pa` informalmente.
|
||||
|
||||
## Current Code Context
|
||||
|
||||
O contexto atual no código Studio é suficiente para ancorar a discussão:
|
||||
|
||||
- o botão `Pack` foi introduzido na action bar do workspace em `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`;
|
||||
- o workspace já possui região inline de progresso, painel de logs e integração com eventos do packer;
|
||||
- ainda não existe wizard de pack nem API explícita de `pack` em `PackerWorkspaceService`.
|
||||
|
||||
Isso significa que o fluxo precisa ser decidido primeiro e depois propagado para:
|
||||
|
||||
- contrato da API do packer;
|
||||
- eventos operacionais de progresso;
|
||||
- modelagem de resultado;
|
||||
- e shell/modal do Studio.
|
||||
|
||||
Leitura operacional explícita:
|
||||
|
||||
- o wizard é Studio-owned apenas como shell de interação;
|
||||
- a semântica do pack é packer-owned ponta a ponta.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Single modal with one primary action
|
||||
|
||||
Abrir um modal com resumo inicial e um único botão `Pack`.
|
||||
Ao confirmar, o Studio valida, empacota e mostra sucesso ou falha no mesmo corpo, sem etapas explícitas de wizard.
|
||||
|
||||
### Option B - Multi-step wizard with explicit operational phases
|
||||
|
||||
Abrir um wizard com fases claras:
|
||||
|
||||
1. `Summary`
|
||||
2. `Validation`
|
||||
3. `Packing`
|
||||
4. `Result`
|
||||
|
||||
Cada fase deixa explícito o estado operacional atual e evita que o usuário perca contexto entre bloqueio, execução e resultado.
|
||||
|
||||
### Option C - Split flow with preflight modal plus separate progress dialog
|
||||
|
||||
Abrir um modal curto para resumo e validação.
|
||||
Se tudo passar, fechar esse modal e abrir outro diálogo dedicado só ao progresso e resultado do pack.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
- Option A é mais rápida de implementar, mas colapsa estados diferentes demais em uma única superfície e tende a virar um modal ambíguo.
|
||||
- Option A também dificulta explicar por que o pack foi bloqueado e o que exatamente falhou por asset.
|
||||
- Option B exige mais estrutura de estado, mas deixa o fluxo didático, previsível e alinhado ao pedido de wizard empacotador.
|
||||
- Option B também facilita mapear cada fase para contratos distintos do packer: preflight, validação, execução e resultado.
|
||||
- Option C separa bem responsabilidades visuais, mas fragmenta a experiência e pode parecer que o usuário saiu de um fluxo para entrar em outro.
|
||||
- Option C ainda aumenta o custo de coordenação de foco, fechamento e recuperação de erro.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adotar `Option B` como baseline.
|
||||
|
||||
O `Pack` deve abrir um wizard modal de workspace.
|
||||
O Studio é owner apenas da apresentação e navegação do modal.
|
||||
O packer é owner da semântica operacional, da validação, da execução e do resultado.
|
||||
|
||||
### Recommended Flow
|
||||
|
||||
#### 1. Summary
|
||||
|
||||
O wizard abre em um resumo do build atual.
|
||||
Esse resumo deve mostrar pelo menos:
|
||||
|
||||
- quantidade de assets registrados e incluídos no build atual;
|
||||
- quantidade de assets excluídos ou fora do build set;
|
||||
- indicação de que o output canônico será `assets.pa`;
|
||||
- indicação de que a `asset_table` seguirá a ordem determinística por `asset_id`, conforme spec;
|
||||
- artefatos companion previstos quando aplicável.
|
||||
|
||||
Regras:
|
||||
|
||||
- assets não incluídos no build não entram no pack;
|
||||
- assets não registrados também não entram no pack;
|
||||
- o resumo deve deixar explícito que a operação trabalha sobre o build set atual, não sobre todo o workspace.
|
||||
- o Studio apenas apresenta esse resumo; ele não recompõe localmente o build set.
|
||||
|
||||
#### 2. Validation
|
||||
|
||||
A segunda fase deve executar uma validação explícita sobre os assets incluídos no build.
|
||||
|
||||
Baseline recomendado:
|
||||
|
||||
- qualquer diagnostic bloqueante em asset incluído falha a validação e impede o início do pack;
|
||||
- a validação deve ser tratada como processo packer-owned semelhante a um `deep sync` dry-run, mas restrito ao conjunto `registered + included in build`;
|
||||
- a tela deve mostrar resumo agregado e amostragem por asset do que falhou;
|
||||
- a UI deve permitir drill-down por asset sem despejar log cru como explicação principal;
|
||||
- se houver warnings não bloqueantes, eles podem ser exibidos, mas não devem impedir o `Pack`.
|
||||
|
||||
Modelo didático mínimo da tela:
|
||||
|
||||
- topo com contagem de assets validados, aprovados e bloqueados;
|
||||
- lista por asset com status;
|
||||
- ao selecionar ou expandir um asset, mostrar diagnostics relevantes daquele asset.
|
||||
|
||||
Baseline fechado nesta agenda wave:
|
||||
|
||||
- a fase de validação mostra diagnostics bloqueantes por padrão;
|
||||
- a tela deve permitir que o developer inspecione contexto adicional quando necessário;
|
||||
- esse drill-down adicional não muda o foco principal da fase, que é explicar o gate de bloqueio.
|
||||
|
||||
A responsabilidade pela classificação do que bloqueia ou não deve permanecer no packer.
|
||||
O Studio apenas consome e apresenta essa classificação.
|
||||
|
||||
Direção mais precisa para esta agenda:
|
||||
|
||||
- a validação não é uma checagem local do Studio;
|
||||
- a validação é uma operação explícita do packer;
|
||||
- ela reutiliza a lógica de reconciliação/inspeção profunda necessária para afirmar se o build set atual pode ser empacotado;
|
||||
- mas seu escopo é apenas o conjunto de assets que realmente participariam do pack.
|
||||
|
||||
#### 3. Packing
|
||||
|
||||
Se a validação passar, o wizard entra em fase de execução.
|
||||
|
||||
Essa fase deve ser não editável, operante e orientada a progresso.
|
||||
|
||||
Regras:
|
||||
|
||||
- mostrar barra de progresso com atualização contínua;
|
||||
- mostrar texto curto da etapa atual;
|
||||
- manter o usuário no mesmo modal até conclusão, falha ou cancelamento suportado por contrato;
|
||||
- deixar explícito que o pack está montando `assets.pa` e a `asset_table` conforme as specs vigentes;
|
||||
- logs detalhados podem existir em área secundária, mas não substituem o indicador principal de progresso.
|
||||
- durante `Packing`, o wizard não deve expor affordances de edição ou revisão que façam a operação parecer reversível ou parcialmente configurável.
|
||||
|
||||
Semântica recomendada:
|
||||
|
||||
- o packer expõe eventos ou snapshots de progresso por operação;
|
||||
- o Studio mapeia isso para uma barra de progresso e rótulos humanos;
|
||||
- o wizard não deve inferir progresso a partir de timers artificiais.
|
||||
|
||||
Baseline fechado para a primeira versão:
|
||||
|
||||
- não há cancelamento durante `Packing`;
|
||||
- o modal permanece em estado operante até conclusão ou falha;
|
||||
- a UI não deve simular cancelamento sem suporte cooperativo real do packer.
|
||||
|
||||
#### 4. Result
|
||||
|
||||
Ao concluir, o wizard deve mostrar um resumo final do resultado.
|
||||
|
||||
O resumo deve cobrir:
|
||||
|
||||
- status final: sucesso parcial ou falha;
|
||||
- quantidade de assets efetivamente empacotados;
|
||||
- artefatos emitidos;
|
||||
- duração da operação;
|
||||
- falhas ou avisos finais, quando existirem.
|
||||
|
||||
Se houver falha depois de a validação ter passado, a tela final deve diferenciar:
|
||||
|
||||
- falha de validação;
|
||||
- falha de execução/geração;
|
||||
- e falha de persistência/emissão.
|
||||
|
||||
Baseline fechado nesta agenda wave:
|
||||
|
||||
- o resumo principal prioriza `assets.pa`, duração e total de assets empacotados;
|
||||
- companion artifacts ficam em drill-down secundário;
|
||||
- os diagnostics do resultado tendem a já existir nos assets e não precisam dominar a superfície principal.
|
||||
|
||||
### Contract Direction
|
||||
|
||||
Para a próxima onda de decisão, o contrato recomendado é separar pelo menos três responsabilidades no packer:
|
||||
|
||||
1. `preflight summary` do build set atual;
|
||||
2. `validation` do build set como dry-run packer-owned semelhante a `deep sync`, com bloqueios agregados por asset;
|
||||
3. `pack execution` com progresso estruturado e resultado final.
|
||||
|
||||
Baseline fechado nesta agenda wave:
|
||||
|
||||
- `summary`, `validation` e `pack execution` são chamadas distintas;
|
||||
- o Studio não deve iniciar `pack execution` para conseguir `summary` ou `validation`;
|
||||
- a separação deve permanecer visível na API consumida pelo Studio.
|
||||
|
||||
O Studio deve orquestrar essas fases no wizard, mas não redefinir:
|
||||
|
||||
- quais assets entram no build set;
|
||||
- o que conta como diagnostic bloqueante;
|
||||
- a ordem da `asset_table`;
|
||||
- ou o que exatamente compõe `assets.pa`.
|
||||
|
||||
Em termos práticos:
|
||||
|
||||
- o Studio chama;
|
||||
- o packer decide;
|
||||
- o Studio mostra.
|
||||
|
||||
### UI Direction
|
||||
|
||||
O wizard deve ser operacional, não um formulário tradicional.
|
||||
|
||||
Direção recomendada:
|
||||
|
||||
- stepper simples no topo ou lateral;
|
||||
- corpo central com conteúdo da fase;
|
||||
- ações de navegação controladas pelo estado operacional;
|
||||
- `Next` bloqueado quando a validação falhar;
|
||||
- `Pack` disponível apenas quando a fase de validação estiver limpa;
|
||||
- `Close` ou `Done` só ao final, ou em estados seguros de abortar.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
Os seguintes pontos ficam fechados como baseline para a próxima `decision`:
|
||||
|
||||
1. `summary`, `validation` e `pack execution` são chamadas distintas.
|
||||
2. A validação mostra diagnostics bloqueantes por padrão e permite inspeção adicional para o developer.
|
||||
3. A primeira versão não suporta cancelamento durante `Packing`.
|
||||
4. Companion artifacts ficam em drill-down secundário no resultado final.
|
||||
5. A primeira versão não exporta nem copia o resumo de falhas.
|
||||
6. Pode existir um botão `dumb` na UI como lembrete explícito de feature futura, sem comportamento operacional no `v1`.
|
||||
|
||||
## Suggested Next Step
|
||||
|
||||
O próximo passo correto é converter esta agenda em uma `decision` owner de `docs/studio`, com propagação explícita para `docs/packer`.
|
||||
|
||||
Essa decision deve fechar:
|
||||
|
||||
1. o shape do wizard e suas fases;
|
||||
2. o gate de validação baseado em diagnostics dos assets incluídos;
|
||||
3. o contrato mínimo de API/eventos que o packer precisa expor para suportar o wizard;
|
||||
4. a distinção entre falha de validação e falha de execução;
|
||||
5. o vocabulário canônico do resultado final em torno de `assets.pa` e `asset_table`.
|
||||
|
||||
Depois disso, o trabalho deve ser decomposto em pelo menos dois planos:
|
||||
|
||||
1. um `PR/plan` em `docs/packer` para summary, validation, pack execution, progress e result contract;
|
||||
2. um `PR/plan` em `docs/studio` para shell do wizard, fases, binding de progresso e tela de resultado.
|
||||
@@ -5,15 +5,8 @@ This directory contains active Studio discussion agendas.
|
||||
Active agendas:
|
||||
|
||||
- [`Palette Management in Studio Agenda.md`](./Palette%20Management%20in%20Studio%20Agenda.md)
|
||||
- [`Asset Bank Composition Area - Dual List and Capacity Meter Agenda.md`](./Asset%20Bank%20Composition%20Area%20-%20Dual%20List%20and%20Capacity%20Meter%20Agenda.md)
|
||||
- [`Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md`](./Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md)
|
||||
- [`Agenda-02-Asset-Bank-Composition-Base-Components.md`](./Agenda-02-Asset-Bank-Composition-Base-Components.md)
|
||||
- [`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](./Agenda-03-Asset-Bank-Composition-Section-Shell.md)
|
||||
- [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](./Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
|
||||
- [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](./Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
||||
- [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](./Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
||||
|
||||
The shell, UI foundations, components admission baselines, and the first asset workspace wave were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/).
|
||||
Closed Studio agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue.
|
||||
|
||||
## Purpose
|
||||
|
||||
|
||||
Reference in New Issue
Block a user