discussion framework migration
This commit is contained in:
@@ -1,20 +0,0 @@
|
||||
# General Documentation
|
||||
|
||||
This directory contains documentation that applies to language implementations in general, not only PBS.
|
||||
|
||||
## Tree
|
||||
|
||||
```text
|
||||
docs/general/
|
||||
└── specs/
|
||||
```
|
||||
|
||||
## Purpose
|
||||
|
||||
`general/specs` is the cross-language acceptance layer.
|
||||
|
||||
Use it to define:
|
||||
|
||||
- shared conformance and quality-gate contracts,
|
||||
- shared compatibility and verification policy,
|
||||
- and backend/runtime acceptance boundaries that are language-agnostic.
|
||||
@@ -2,22 +2,35 @@
|
||||
|
||||
This directory contains active PBS discussion agendas.
|
||||
|
||||
Closed agendas are moved to `docs/pbs/agendas/archive`.
|
||||
Closed agendas are moved to `docs/compiler/pbs/agendas/archive`.
|
||||
|
||||
## Active Agendas
|
||||
|
||||
1. `18.0. Backend VM Pipeline - Orchestration Agenda.md`
|
||||
2. `18.1. Backend Workshop 1 - IRBackend Input Contract.md`
|
||||
3. `18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md`
|
||||
4. `18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md`
|
||||
5. `18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md`
|
||||
6. `18.5. Ignored Call Results in Executable Lowering Agenda.md`
|
||||
7. `19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md`
|
||||
8. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md`
|
||||
9. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
|
||||
10. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
|
||||
11. `19.4. Globals and Lifecycle Lowering to IRBackend-IRVM Agenda.md`
|
||||
12. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
|
||||
1. `18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md`
|
||||
2. `18.5. Ignored Call Results in Executable Lowering Agenda.md`
|
||||
3. `19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md`
|
||||
4. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md`
|
||||
5. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
|
||||
6. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
|
||||
7. `19.4. Globals and Lifecycle Lowering to IRBackend-IRVM Agenda.md`
|
||||
8. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
|
||||
|
||||
## Consolidated Agenda 18 Material
|
||||
|
||||
Agenda 18 backend-orchestration material (`18.0` through `18.3`) is no longer part of the active agenda set.
|
||||
|
||||
That slice has already been propagated into:
|
||||
|
||||
1. the backend execution plan in `docs/compiler/pbs/pull-requests/INDEX.md` under `Backend VM Pipeline PR Sequence (Agenda 18)`,
|
||||
2. decision material such as `docs/compiler/pbs/decisions/IRVM Optimization Stage Placement Decision.md`,
|
||||
3. normative backend specs:
|
||||
- `docs/compiler/general/specs/19. Verification and Safety Checks Specification.md`,
|
||||
- `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`,
|
||||
- `docs/compiler/general/specs/21. IRVM Optimization Pipeline Specification.md`,
|
||||
- `docs/compiler/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`,
|
||||
4. and implemented/tested backend pipeline stages in `prometeu-compiler/prometeu-build-pipeline`.
|
||||
|
||||
Only `18.4` and `18.5` remain open from the `18.*` family.
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -30,7 +43,7 @@ Use an agenda when:
|
||||
- the scope and non-goals need to be made explicit,
|
||||
- the order of discussion matters.
|
||||
|
||||
Move an agenda to `docs/pbs/agendas/archive` once the topic is no longer active.
|
||||
Move an agenda to `docs/compiler/pbs/agendas/archive` once the topic is no longer active.
|
||||
|
||||
## Expected Format
|
||||
|
||||
|
||||
@@ -1,112 +0,0 @@
|
||||
# Packer Documentation
|
||||
|
||||
This directory contains the working, planning, normative, and didactic documentation for the `packer` domain.
|
||||
|
||||
`packer` is a standalone domain. It follows the same documentary cycle used elsewhere in the repository:
|
||||
|
||||
`agendas -> decisions -> pull-requests -> specs -> learn`
|
||||
|
||||
## Tree
|
||||
|
||||
```text
|
||||
docs/packer/
|
||||
├── agendas/
|
||||
├── decisions/
|
||||
├── learn/
|
||||
├── pull-requests/
|
||||
├── specs/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Responsibilities
|
||||
|
||||
### `agendas/`
|
||||
|
||||
`agendas/` is a transient staging area for open packer topics.
|
||||
|
||||
Use it to:
|
||||
|
||||
- frame unresolved problems,
|
||||
- compare options and tradeoffs,
|
||||
- define scope and non-goals,
|
||||
- drive discussions toward a decision.
|
||||
|
||||
An agenda is a discussion artifact, not a final contract.
|
||||
When a topic is fully propagated into specs and learn, the corresponding agenda should leave the retained set.
|
||||
|
||||
### `decisions/`
|
||||
|
||||
`decisions/` is a transient staging area for closed packer decisions before full consolidation.
|
||||
|
||||
Use it to:
|
||||
|
||||
- record the chosen direction,
|
||||
- capture constraints and invariants,
|
||||
- state what remains intentionally out of scope,
|
||||
- identify which specs, plans, or code paths must be updated.
|
||||
|
||||
Decisions close debate. They are not brainstorming notes.
|
||||
Once their content is fully absorbed into specs and learn, they should not be retained just as historical residue.
|
||||
|
||||
### `pull-requests/`
|
||||
|
||||
`pull-requests/` contains self-contained execution proposals.
|
||||
|
||||
Use it to:
|
||||
|
||||
- package a change for review,
|
||||
- plan propagation across specs and implementation,
|
||||
- define acceptance criteria,
|
||||
- make tests and risks explicit before editing code or final specs.
|
||||
|
||||
### `specs/`
|
||||
|
||||
`specs/` contains the normative packer corpus.
|
||||
|
||||
Use it to:
|
||||
|
||||
- consolidate the official packer contract,
|
||||
- split large draft material into stable chaptered specs,
|
||||
- define behavior, constraints, interfaces, and conformance expectations.
|
||||
|
||||
Specs should only absorb already-closed decisions.
|
||||
|
||||
### `learn/`
|
||||
|
||||
`learn/` contains didactic consolidation.
|
||||
|
||||
Use it to:
|
||||
|
||||
- explain why the packer works the way it does,
|
||||
- preserve hard-won operational knowledge,
|
||||
- teach future contributors the model, pitfalls, and expected workflows,
|
||||
- reorganize accumulated knowledge into a cleaner learning surface.
|
||||
|
||||
`learn/` is not an archive of old decisions.
|
||||
|
||||
## Recommended Flow
|
||||
|
||||
The preferred packer documentation flow is:
|
||||
|
||||
1. `agendas/`: open and shape the unresolved topic.
|
||||
2. `decisions/`: close the architectural choice.
|
||||
3. `pull-requests/`: plan how the decision will be propagated.
|
||||
4. `specs/`: integrate the decision into normative text.
|
||||
5. `learn/`: consolidate the final knowledge in a didactic form.
|
||||
|
||||
## Practical Rule
|
||||
|
||||
- `agendas/` stores currently open questions only.
|
||||
- `decisions/` stores only decisions that still need propagation.
|
||||
- `pull-requests/` stores only execution plans for pending work.
|
||||
- `specs/` stores the normative packer contract.
|
||||
- `learn/` stores teaching-oriented consolidation.
|
||||
|
||||
The current packer core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/).
|
||||
At this moment:
|
||||
|
||||
- `agendas/` retains only topics that are still open;
|
||||
- `decisions/` is empty because the last accepted wave was fully propagated;
|
||||
- `pull-requests/` is empty because the historical execution wave was absorbed into `learn/`.
|
||||
|
||||
If implementation exposes a missing architectural choice, stop and return to `agendas/` or `decisions/`.
|
||||
@@ -1,54 +0,0 @@
|
||||
# Packer Agendas
|
||||
|
||||
This directory contains active packer discussion agendas.
|
||||
|
||||
## Active Agendas
|
||||
|
||||
1. [`Tilemap and Metatile Runtime Binary Layout Agenda.md`](./Tilemap%20and%20Metatile%20Runtime%20Binary%20Layout%20Agenda.md)
|
||||
2. [`Variable Tile Bank Palette Serialization Agenda.md`](./Variable%20Tile%20Bank%20Palette%20Serialization%20Agenda.md)
|
||||
|
||||
Closed packer agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue.
|
||||
|
||||
## Purpose
|
||||
|
||||
An agenda exists to drive a decision.
|
||||
|
||||
Use an agenda when:
|
||||
|
||||
- the packer topic is still open,
|
||||
- multiple options or tradeoffs must be evaluated,
|
||||
- scope and non-goals need to be made explicit,
|
||||
- the order of discussion matters,
|
||||
- the team still needs a recommendation before committing direction.
|
||||
|
||||
An agenda should help the reader converge, not just accumulate notes.
|
||||
|
||||
## Expected Format
|
||||
|
||||
A packer agenda should usually include:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Purpose
|
||||
4. Context
|
||||
5. Options
|
||||
6. Tradeoffs
|
||||
7. Recommendation
|
||||
8. Open Questions
|
||||
9. Expected Follow-up
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Keep the document centered on unresolved questions.
|
||||
- State the concrete decision the discussion is trying to produce.
|
||||
- Prefer explicit tradeoffs over vague option lists.
|
||||
- Avoid drafting large blocks of final normative spec text here.
|
||||
- Be specific about packer scope: asset workspace, build artifacts, diagnostics, registry, shipper boundary, and related contracts.
|
||||
|
||||
## Exit Rule
|
||||
|
||||
An agenda should leave the active set when:
|
||||
|
||||
- the main tradeoffs are understood,
|
||||
- a recommendation is clear enough to adopt,
|
||||
- and the topic is ready to become a decision record.
|
||||
@@ -1,152 +0,0 @@
|
||||
# Tilemap and Metatile Runtime Binary Layout Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## Purpose
|
||||
|
||||
Convergir a discussão sobre o contrato de mapa para handheld em duas camadas:
|
||||
|
||||
- formato de autoria/edição (JSON legível),
|
||||
- formato de execução (layout binário compacto em runtime).
|
||||
|
||||
O objetivo é fechar qual estrutura será adotada para `tilemap bank`, `tileset bank` e dados de colisão/flags, com foco em previsibilidade de memória e streaming de mapas.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/packer`
|
||||
|
||||
Este tema é owner de packer porque envolve transformação de artefatos (`JSON -> BIN`), contrato de build e layout de saída para consumo do runtime.
|
||||
|
||||
Domínios impactados (cross-domain):
|
||||
|
||||
- `docs/vm-arch` (contrato de leitura em runtime e limites de memória),
|
||||
- `docs/studio` (edição/preview de mapas no workspace),
|
||||
- `docs/compiler/pbs` (integração futura com referências de assets em código, quando aplicável).
|
||||
|
||||
## Problem
|
||||
|
||||
Hoje existe alinhamento conceitual de que:
|
||||
|
||||
1. visual e colisão devem ser separados por responsabilidade;
|
||||
2. o mapa não deve repetir metadados extensos por célula;
|
||||
3. apenas uma janela ativa de até `9` mapas deve ficar residente em memória.
|
||||
|
||||
Mas ainda não existe decisão formal sobre:
|
||||
|
||||
- layout binário final por célula em runtime,
|
||||
- orçamento por mapa e por janela ativa,
|
||||
- responsabilidade exata entre `map bank` e `tileset bank`.
|
||||
|
||||
Sem esse contrato, o packer não fecha especificação de saída e o runtime/studio ficam sem baseline único.
|
||||
|
||||
## Context
|
||||
|
||||
Premissas atuais da discussão:
|
||||
|
||||
- `tileset bank` pode ter tamanho diferente dos demais banks;
|
||||
- `map bank` não precisa seguir o mesmo tamanho de `tileset bank`;
|
||||
- mapa deve referenciar IDs compactos (visual, colisão e flags), em vez de duplicar estrutura completa por célula;
|
||||
- paletas por bank continuam sendo opção válida para preservar decisões artísticas locais;
|
||||
- orçamento alvo foi discutido no contexto de `64 KiB` por map bank e janela ativa de `3x3` mapas (`9` residentes).
|
||||
|
||||
## Options
|
||||
|
||||
### Option A — Célula `u8` (mapa ultra-compacto)
|
||||
|
||||
- Cada célula armazena apenas `metatileId` (`0..255`).
|
||||
- Colisão/flags vêm de tabela auxiliar por `metatileId`.
|
||||
|
||||
### Option B — Célula `u16` bit-packed (recomendação inicial)
|
||||
|
||||
- Cada célula usa `16 bits` com divisão sugerida:
|
||||
- `visualId`: `10 bits` (`0..1023`),
|
||||
- `collisionId`: `5 bits` (`0..31`),
|
||||
- `flags`: `1 bit` (`0..1`) ou reservado para evolução.
|
||||
- Permite desacoplamento visual/lógico sem custo de `u32`.
|
||||
|
||||
### Option C — Célula `u32` (maior flexibilidade)
|
||||
|
||||
- Exemplo de divisão:
|
||||
- `visualId`: `12 bits`,
|
||||
- `collisionId`: `8 bits`,
|
||||
- `flags/event`: `12 bits`.
|
||||
- Ganho de expressividade para triggers/eventos inline; custo de memória dobra vs `u16`.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
- Option A minimiza RAM e I/O, mas limita variedade visual e desloca muita semântica para tabelas externas.
|
||||
- Option B oferece bom equilíbrio para handheld: compacta, previsível e com espaço suficiente para muitos casos de mapa.
|
||||
- Option C simplifica evolução funcional (eventos por célula), mas pressiona memória e banda de streaming sem necessidade comprovada agora.
|
||||
|
||||
## Runtime Binary Structure (focus)
|
||||
|
||||
Estrutura sugerida para runtime (baseada em Option B):
|
||||
|
||||
1. **Map Header (fixo)**
|
||||
- `magic` (`4 bytes`)
|
||||
- `version` (`u16`)
|
||||
- `width` (`u16`)
|
||||
- `height` (`u16`)
|
||||
- `cellEncoding` (`u8`) — ex.: `1 = U16_PACKED_V1`
|
||||
- `visualBankId` (`u16`)
|
||||
- `collisionBankId` (`u16`)
|
||||
- `reserved` / `checksum` (conforme decisão posterior)
|
||||
|
||||
2. **Cell Stream**
|
||||
- vetor contínuo com `width * height` células `u16`, little-endian;
|
||||
- leitura linear favorece cache e descompressão simples.
|
||||
|
||||
3. **Optional Chunks (future-proof)**
|
||||
- bloco opcional de `eventTriggers`;
|
||||
- bloco opcional de `spawnPoints`;
|
||||
- bloco opcional de `navHints`.
|
||||
|
||||
Packing de célula (`U16_PACKED_V1`):
|
||||
|
||||
- `bits 0..9` => `visualId`
|
||||
- `bits 10..14` => `collisionId`
|
||||
- `bit 15` => `flag0`
|
||||
|
||||
Decodificação de referência:
|
||||
|
||||
- `visualId -> metatile visual table -> 4 subtiles (8x8) + palette/flip/priority`
|
||||
- `collisionId -> collision/material table -> walk/solid/swim/damage/etc.`
|
||||
|
||||
## Memory Notes for Active Window (`9` maps)
|
||||
|
||||
Assumindo `64 KiB` por map bank:
|
||||
|
||||
- `1` mapa residente: `64 KiB`
|
||||
- `9` mapas residentes: `576 KiB`
|
||||
|
||||
Capacidade por encoding dentro de `64 KiB`:
|
||||
|
||||
- `u8`: `65,536` células (`256x256` máximo quadrado)
|
||||
- `u16`: `32,768` células (`~181x181` máximo quadrado, ou retângulos equivalentes)
|
||||
- `u32`: `16,384` células (`128x128` máximo quadrado)
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adotar `Option B` como baseline para decisão:
|
||||
|
||||
1. autoria em JSON orientada a IDs (`visualId`, `collisionId`, `flags`);
|
||||
2. empacotamento determinístico para `U16_PACKED_V1` no build;
|
||||
3. janela ativa de runtime limitada a `9` mapas com budget explícito;
|
||||
4. extensão para `u32` somente via nova versão de encoding e evidência de necessidade.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. `collisionId` com `5 bits` (`32` classes) é suficiente para os biomas/projetos previstos?
|
||||
2. `flag0` deve ser reservado para trigger rápido ou para variação visual contextual?
|
||||
3. Quais chunks opcionais entram já em `V1` e quais ficam para `V2`?
|
||||
4. O `map bank` seguirá estritamente `64 KiB` ou terá tamanho variável com metadado de capacidade?
|
||||
5. Qual política de compressão do stream (`none`, `LZ4`, etc.) será padrão no packer?
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
1. Abrir `decision` em `docs/packer/decisions` fechando o encoding `U16_PACKED_V1`.
|
||||
2. Propagar contrato de leitura para `docs/vm-arch`.
|
||||
3. Definir no `docs/studio/specs` o schema de edição JSON correspondente.
|
||||
4. Planejar PR de implementação (`packer` + `runtime`) com testes de roundtrip (`JSON -> BIN -> decode`).
|
||||
@@ -1,142 +0,0 @@
|
||||
# Variable Tile Bank Palette Serialization Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Active
|
||||
|
||||
## Domain Owner
|
||||
|
||||
- `docs/packer`
|
||||
|
||||
Cross-domain dependency:
|
||||
|
||||
- `../runtime`
|
||||
|
||||
## Purpose
|
||||
|
||||
Decide whether `tile bank` payloads should keep serializing a fixed block of `64` palettes in v1, or evolve to serialize only the palettes actually authored by the asset.
|
||||
|
||||
## Context
|
||||
|
||||
The current `tile bank` contract is aligned between `packer` and `runtime`:
|
||||
|
||||
- pixels are serialized as packed `u4`;
|
||||
- palettes are serialized as `RGB565 u16`;
|
||||
- `palette_count = 64`;
|
||||
- payload size is derived from `ceil(width * height / 2) + (64 * 16 * 2)`.
|
||||
|
||||
This means a `tile bank` with `1` authored palette still serializes `64` palette slots. Unused slots are currently zero-filled, which is valid for the runtime, but wastes cartridge space.
|
||||
|
||||
The packer now exposes:
|
||||
|
||||
- `metadata.palette_count = 64`
|
||||
- `metadata.palette_authored = <actual authored count>`
|
||||
|
||||
This makes the waste explicit, but does not remove it.
|
||||
|
||||
## Problem
|
||||
|
||||
The runtime-facing v1 contract favors fixed-size decode simplicity over cartridge efficiency.
|
||||
|
||||
We need to decide whether:
|
||||
|
||||
1. fixed `64` palette slots remain the normative contract for `tile bank`;
|
||||
2. `palette_count` becomes variable and payload size shrinks to the authored set;
|
||||
3. another staged strategy is better.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A: Keep Fixed 64-Palette Serialization
|
||||
|
||||
Keep the current contract unchanged:
|
||||
|
||||
- `palette_count` remains `64`;
|
||||
- every `tile bank` serializes `64 * 16 * 2 = 2048` bytes of palettes;
|
||||
- authored palettes populate their indexed slots;
|
||||
- unused slots are zero-filled.
|
||||
|
||||
### Option B: Move to Variable Palette Serialization
|
||||
|
||||
Evolve the contract so `tile bank` serializes only authored palettes:
|
||||
|
||||
- `palette_count` becomes the authored count;
|
||||
- payload size becomes `ceil(width * height / 2) + (palette_count * 16 * 2)`;
|
||||
- runtime validates and decodes variable palette blocks.
|
||||
|
||||
### Option C: Keep V1 Fixed, Design Variable Serialization for V2
|
||||
|
||||
Preserve the current runtime-facing v1 contract now, but explicitly open a v2 format/contract:
|
||||
|
||||
- v1 stays fixed at `64`;
|
||||
- v2 introduces variable palette serialization;
|
||||
- packer and runtime keep clear compatibility boundaries.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
### Option A
|
||||
|
||||
Pros:
|
||||
|
||||
- no further runtime work;
|
||||
- simplest decode path;
|
||||
- current specs and tests stay valid.
|
||||
|
||||
Cons:
|
||||
|
||||
- every `tile bank` pays the full 2 KB palette cost;
|
||||
- cartridge size is inflated for small authored palette sets;
|
||||
- the metadata now exposes a mismatch between authored and serialized counts by design.
|
||||
|
||||
### Option B
|
||||
|
||||
Pros:
|
||||
|
||||
- reduces cartridge size;
|
||||
- makes `palette_count` semantically tighter;
|
||||
- removes fixed empty palette padding from the payload.
|
||||
|
||||
Cons:
|
||||
|
||||
- requires coordinated changes in `packer`, `runtime`, specs, and tests;
|
||||
- changes the `size` / `decoded_size` formulas;
|
||||
- raises compatibility and migration questions for existing assets and cartridges.
|
||||
|
||||
### Option C
|
||||
|
||||
Pros:
|
||||
|
||||
- keeps current work stable;
|
||||
- makes room for a cleaner future contract;
|
||||
- avoids mixing optimization work into the current tile-bank rollout.
|
||||
|
||||
Cons:
|
||||
|
||||
- known waste remains in v1;
|
||||
- adds future format/version management work.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Recommendation for now: `Option C`.
|
||||
|
||||
Reasoning:
|
||||
|
||||
- the current fixed-size contract is already implemented and aligned;
|
||||
- the waste is real, but it is not a correctness bug;
|
||||
- changing it now would reopen a cross-domain runtime contract that was just stabilized;
|
||||
- if we want variable palette serialization, it should be introduced deliberately as a versioned follow-up, not as an incidental tweak.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should variable palette serialization be introduced as a new `tile bank` payload version, or as an incompatible change to the current one?
|
||||
2. If `palette_count` becomes variable, should runtime still materialize a 64-slot bank in memory, or truly shrink the resident representation too?
|
||||
3. Should palette slot identity remain sparse by authored `index`, or should serialization canonicalize into a dense runtime block?
|
||||
4. Which domain owns the compatibility story for existing cartridges: `packer`, `runtime`, or `shipper`?
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
If the team wants to eliminate the fixed 64-palette padding:
|
||||
|
||||
1. create a corresponding runtime agenda/decision;
|
||||
2. define the versioning and compatibility story;
|
||||
3. update `packer` and `runtime` specs together;
|
||||
4. then plan code changes in both domains.
|
||||
@@ -1,53 +0,0 @@
|
||||
# Packer Decisions
|
||||
|
||||
This directory contains packer decision records that still need propagation.
|
||||
|
||||
Current retained set:
|
||||
|
||||
- none
|
||||
|
||||
The current packer decision wave has already been consolidated into:
|
||||
|
||||
- normative specifications under [`../specs/`](../specs/)
|
||||
- didactic material under [`../learn/`](../learn/)
|
||||
|
||||
## Purpose
|
||||
|
||||
A decision record is the bridge between packer discussion and packer execution.
|
||||
|
||||
Use this directory to capture:
|
||||
|
||||
- what was decided,
|
||||
- why that direction was chosen,
|
||||
- which constraints now apply,
|
||||
- what remains intentionally undecided,
|
||||
- which specs, plans, tests, or implementations must be updated.
|
||||
|
||||
A decision should be stable enough that a spec or implementation worker can act on it without reconstructing the original debate.
|
||||
|
||||
## Expected Format
|
||||
|
||||
A packer decision should usually include:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Date or Cycle
|
||||
4. Context
|
||||
5. Decision
|
||||
6. Invariants and Constraints
|
||||
7. Explicit Non-Decisions
|
||||
8. Propagation Targets
|
||||
9. Validation Notes or Examples
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- State the adopted decision early and clearly.
|
||||
- Write in stable language, not in exploratory tone.
|
||||
- Capture architectural constraints explicitly.
|
||||
- Record what is still not decided so later work does not guess.
|
||||
- Point to the exact packer specs, PRs, or code areas that need propagation.
|
||||
|
||||
## Implementation Rule
|
||||
|
||||
If implementation work reveals a missing decision, do not infer it.
|
||||
Return the issue to agenda or decision review.
|
||||
@@ -1,59 +0,0 @@
|
||||
# Packer Learn
|
||||
|
||||
This directory contains didactic packer knowledge.
|
||||
|
||||
## Purpose
|
||||
|
||||
`learn/` exists to teach, not merely to store historical leftovers.
|
||||
|
||||
Use it to:
|
||||
|
||||
- explain packer architecture in a way new contributors can absorb quickly,
|
||||
- consolidate conclusions from completed decisions and PRs,
|
||||
- document common pitfalls and anti-patterns,
|
||||
- connect normative specs to practical reasoning and implementation reality.
|
||||
|
||||
## What Belongs Here
|
||||
|
||||
A `learn` artifact should usually include:
|
||||
|
||||
1. the original problem,
|
||||
2. the decision that resolved it,
|
||||
3. the implemented or specified final model,
|
||||
4. practical examples,
|
||||
5. common mistakes and warnings,
|
||||
6. links to the relevant specs and PRs.
|
||||
|
||||
Good `learn` material reduces onboarding time and prevents the same architectural confusion from repeating.
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Prefer didactic structure over chronological accumulation.
|
||||
- Explain why the model exists, not only what it is.
|
||||
- Keep terminology aligned with packer specs.
|
||||
- Refactor older material when the directory starts feeling like a document graveyard.
|
||||
|
||||
## Refactor Rule
|
||||
|
||||
This directory should be periodically reorganized for better presentation.
|
||||
|
||||
If content grows, prefer:
|
||||
|
||||
- thematic grouping,
|
||||
- overview documents,
|
||||
- explicit learning paths,
|
||||
- and consolidation of duplicated explanations.
|
||||
|
||||
The goal is a maintainable learning surface, not a passive archive.
|
||||
|
||||
## Current Learning Path
|
||||
|
||||
Start here:
|
||||
|
||||
1. [`mental-model-packer.md`](./mental-model-packer.md)
|
||||
2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
|
||||
3. [`foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md)
|
||||
4. [`runtime-ownership-and-studio-boundary.md`](./runtime-ownership-and-studio-boundary.md)
|
||||
5. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)
|
||||
6. [`pack-wizard-summary-validation-and-pack-execution.md`](./pack-wizard-summary-validation-and-pack-execution.md)
|
||||
7. [`tile-bank-packing-contract.md`](./tile-bank-packing-contract.md)
|
||||
@@ -1,91 +0,0 @@
|
||||
# Foundations: Workspace, Runtime, and Build
|
||||
|
||||
## Original Problem
|
||||
|
||||
The packer domain accumulated a long implementation wave covering workspace control, asset identity, scanning, mutations, diagnostics, deterministic planning, runtime snapshots, and cache reuse.
|
||||
|
||||
The historical PR chain was useful while the repository was converging, but it stopped being a good onboarding surface:
|
||||
|
||||
- too much knowledge was spread across execution slices;
|
||||
- too much reasoning depended on chronological reconstruction;
|
||||
- too little of that knowledge was available as one stable mental model.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The stable packer foundation is:
|
||||
|
||||
1. the workspace stays open and filesystem-first;
|
||||
2. `assets/.prometeu/index.json` owns managed identity and inclusion state;
|
||||
3. each asset root is anchored by `asset.json`;
|
||||
4. the packer runtime serves coherent snapshot-backed reads;
|
||||
5. writes are coordinated by the packer and become visible after durable commit;
|
||||
6. build outputs are derived deterministically from validated, packer-owned state.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Workspace and Identity
|
||||
|
||||
- `asset_id` is the stable managed identifier used for ordering, inclusion, and runtime-facing tables;
|
||||
- `asset_uuid` is the local identity anchor that helps reconcile the same logical asset across path movement;
|
||||
- `asset_name` is the logical human-facing identifier and is not a substitute for managed identity;
|
||||
- `asset.json` describes authoring intent, not registry-owned bookkeeping.
|
||||
|
||||
### 2. Read and Write Authority
|
||||
|
||||
- normal reads come from a coherent runtime snapshot rather than from ad hoc filesystem scans;
|
||||
- the filesystem still matters because it remains the durable authoring surface;
|
||||
- writes flow through packer-owned preview/apply semantics and one project-scoped serialized lane.
|
||||
|
||||
### 3. Deterministic Build Path
|
||||
|
||||
- only validated managed assets enter the build path;
|
||||
- asset ordering is deterministic by increasing `asset_id`;
|
||||
- runtime-facing artifacts are emitted from canonical packer-owned planning and materialization rules;
|
||||
- companion artifacts mirror build authority rather than define parallel truth.
|
||||
|
||||
### 4. Runtime Snapshot Evolution
|
||||
|
||||
The later runtime wave refined the first foundation:
|
||||
|
||||
- runtime state became explicitly project-scoped;
|
||||
- snapshot updates happen after successful write commit;
|
||||
- query services read from that runtime state;
|
||||
- cache layers exist to accelerate the same ownership model, not to bypass it.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why relocation does not create a new asset
|
||||
|
||||
If an asset root moves on disk, the packer should preserve the managed identity when the move is a relocation of the same logical asset.
|
||||
|
||||
That is why:
|
||||
|
||||
- the registry owns stable managed identity;
|
||||
- path is mutable operational state;
|
||||
- relocation updates root tracking without inventing a new `asset_id`.
|
||||
|
||||
### Example: Why filesystem order cannot define build order
|
||||
|
||||
Two equivalent workspaces may be traversed in different directory order.
|
||||
The build must still emit the same `asset_table` and payload layout.
|
||||
|
||||
That is why deterministic ordering is tied to managed identity, not traversal order.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating `asset_name` as if it were a stable runtime identifier.
|
||||
- Moving registry-owned fields into `asset.json`.
|
||||
- Recomputing semantic read models directly from Studio-side filesystem heuristics.
|
||||
- Letting build order depend on traversal order, cache insertion order, or UI ordering.
|
||||
- Treating cache state as semantic authority instead of as an optimization.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./mental-model-packer.md`](./mental-model-packer.md)
|
||||
- [`./mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
|
||||
@@ -1,95 +0,0 @@
|
||||
# Asset Identity and Runtime Contract
|
||||
|
||||
This document explains the point that is easiest to get subtly wrong:
|
||||
|
||||
- `asset_id` is the stable artifact identity;
|
||||
- `asset_name` is still a logical code-facing reference.
|
||||
|
||||
If you flatten those two concepts into one, the architecture starts drifting immediately.
|
||||
|
||||
## The Stable Side: `asset_id`
|
||||
|
||||
`asset_id` is allocated by the packer registry.
|
||||
|
||||
It is stable within the project and appears in runtime-facing artifacts.
|
||||
|
||||
Why this matters:
|
||||
|
||||
- preload uses `asset_id`;
|
||||
- artifact identity survives move and rename;
|
||||
- build outputs remain structurally stable even when authoring layout changes.
|
||||
|
||||
`asset_id` is the answer to:
|
||||
|
||||
> “Is this the same asset as before?”
|
||||
|
||||
## The Logical Side: `asset_name`
|
||||
|
||||
`asset_name` remains useful because game-facing code and runtime APIs still refer to assets by name in normal flows.
|
||||
|
||||
Why this matters:
|
||||
|
||||
- authors need a readable label;
|
||||
- game code usually references assets semantically, not by integer literal;
|
||||
- runtime lookup still uses names in parts of the current operational surface.
|
||||
|
||||
`asset_name` is the answer to:
|
||||
|
||||
> “What do humans and source code call this asset?”
|
||||
|
||||
## Why Not Use Only One Of Them?
|
||||
|
||||
If you use only `asset_name`:
|
||||
|
||||
- rename becomes identity breakage;
|
||||
- preload/bootstrap integrity becomes fragile;
|
||||
- build artifacts depend too much on mutable author intent.
|
||||
|
||||
If you use only `asset_id` everywhere today:
|
||||
|
||||
- source code becomes less ergonomic;
|
||||
- authoring workflows become harder to read;
|
||||
- the current runtime/game-facing API model would need stronger compile-time lowering infrastructure.
|
||||
|
||||
So the current architecture intentionally keeps both:
|
||||
|
||||
- stable identity for artifacts;
|
||||
- logical naming for authoring and API usage.
|
||||
|
||||
## What Actually Happens In The Artifact?
|
||||
|
||||
The runtime-facing asset table carries both:
|
||||
|
||||
- `asset_id`
|
||||
- `asset_name`
|
||||
|
||||
But they play different roles.
|
||||
|
||||
`asset_id`:
|
||||
|
||||
- defines stable identity;
|
||||
- is used for preload/bootstrap integrity.
|
||||
|
||||
`asset_name`:
|
||||
|
||||
- stays in the table as descriptive/API-facing metadata;
|
||||
- supports name-based lookup where that still exists.
|
||||
|
||||
## Why This Is Still Not The End Of The Story
|
||||
|
||||
There is still an open language/toolchain question:
|
||||
|
||||
- should source-level asset references remain name-based forever?
|
||||
- or should the compiler eventually lower known references to stable IDs or resource handles?
|
||||
|
||||
That is a separate problem from the packer artifact identity model.
|
||||
It belongs to language/frontend and runtime API design, not to the core packer identity rules.
|
||||
|
||||
## Practical Rule
|
||||
|
||||
When reading or implementing packer behavior, use this checklist:
|
||||
|
||||
- if the question is about stable artifact identity, think `asset_id`;
|
||||
- if the question is about source naming or human-facing lookup, think `asset_name`;
|
||||
- if the question is about preload/bootstrap correctness, prefer `asset_id`;
|
||||
- if the question is about runtime/game API ergonomics, `asset_name` may still be intentionally present.
|
||||
@@ -1,78 +0,0 @@
|
||||
# Metadata Convergence and Runtime Sink (`AssetEntry.metadata`)
|
||||
|
||||
## Original Problem
|
||||
|
||||
Packer authoring contracts may carry metadata from different concerns:
|
||||
|
||||
- asset/runtime contract metadata;
|
||||
- codec-related metadata;
|
||||
- pipeline-derived metadata generated during materialization.
|
||||
|
||||
Without an explicit convergence rule, teams drift into ambiguous behavior:
|
||||
|
||||
- runtime readers are unsure where effective values must be read;
|
||||
- metadata merge behavior becomes accidental and non-deterministic;
|
||||
- payload slicing fields can be confused with internal indexing offsets.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The accepted direction is:
|
||||
|
||||
1. all runtime-consumable metadata converges to a single sink: `AssetEntry.metadata`;
|
||||
2. source segmentation in `asset.json` is allowed for authoring ergonomics;
|
||||
3. build/materialization must normalize sources deterministically;
|
||||
4. collisions require explicit contract rules or must fail build;
|
||||
5. `AssetEntry.offset`/`AssetEntry.size` keep payload slicing semantics and do not replace internal pipeline indexing.
|
||||
|
||||
## Final Model
|
||||
|
||||
Think in two layers:
|
||||
|
||||
- **Authoring layer**: source metadata may be segmented by concern;
|
||||
- **Runtime layer**: one effective metadata map in each emitted asset entry.
|
||||
|
||||
Practical rule for runtime consumers:
|
||||
|
||||
- if the value is runtime-consumable metadata, read it from `AssetEntry.metadata`.
|
||||
|
||||
Practical rule for packer implementation:
|
||||
|
||||
- normalize all relevant metadata sources into `AssetEntry.metadata` during build;
|
||||
- keep normalization deterministic and testable.
|
||||
|
||||
## Example (Audio Bank Indexing)
|
||||
|
||||
Illustrative normalized metadata shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"sample_rate": 22050,
|
||||
"channels": 1,
|
||||
"samples": {
|
||||
"1": { "offset": 0, "length": 100 }
|
||||
},
|
||||
"codec": {
|
||||
"parity": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this model:
|
||||
|
||||
- `samples[*].offset/length` are internal indexing values for the audio payload contract;
|
||||
- they are not the same thing as `AssetEntry.offset/size` in the asset table.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating segmented declaration metadata as multiple runtime sinks.
|
||||
- Allowing silent key overwrite when two metadata sources collide.
|
||||
- Mixing payload slicing semantics (`asset_table[].offset/size`) with internal indexing semantics (`metadata.samples[*].offset/length`).
|
||||
- Documenting convergence behavior only in code comments and not in normative specs.
|
||||
|
||||
## References
|
||||
|
||||
- Spec: [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- Spec: [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- Related learn: [`./tile-bank-packing-contract.md`](./tile-bank-packing-contract.md)
|
||||
@@ -1,87 +0,0 @@
|
||||
# Packer Mental Model
|
||||
|
||||
The packer is not a cartridge shipper, not a runtime reader, and not a random file janitor.
|
||||
It is the system that turns an asset workspace into stable asset artifacts.
|
||||
|
||||
The easiest way to understand it is through five questions.
|
||||
|
||||
## 1. What is the unit of management?
|
||||
|
||||
The unit is the managed asset root.
|
||||
|
||||
One managed asset:
|
||||
|
||||
- lives in one asset root directory;
|
||||
- has one anchor `asset.json`;
|
||||
- may include many internal files as inputs.
|
||||
|
||||
This is why an atlas, image bank, or grouped sound bundle can still be one asset.
|
||||
The managed asset is the output unit, not each source file.
|
||||
|
||||
## 2. Where is the source of truth?
|
||||
|
||||
There are two different truths for two different jobs:
|
||||
|
||||
- `assets/.prometeu/index.json` tells the packer which assets are officially managed;
|
||||
- each `asset.json` tells the packer what that asset declares locally.
|
||||
|
||||
This split matters.
|
||||
Without it, copy/move/register flows become ambiguous very quickly.
|
||||
|
||||
## 3. What is the difference between `asset_id` and `asset_name`?
|
||||
|
||||
They are not the same thing.
|
||||
|
||||
`asset_id` is the stable identity.
|
||||
It survives moves and renames.
|
||||
|
||||
`asset_name` is the logical reference label.
|
||||
It is the thing source code and runtime-facing APIs may still use today.
|
||||
|
||||
That means:
|
||||
|
||||
- renaming `asset_name` is not an identity change;
|
||||
- but it can still be an API-visible change.
|
||||
|
||||
This is the most important distinction to keep in your head while reading the packer and runtime contracts.
|
||||
|
||||
## 4. What is the runtime-facing artifact?
|
||||
|
||||
`assets.pa`.
|
||||
|
||||
That is the artifact the runtime reads.
|
||||
It is authoritative for runtime-facing asset metadata.
|
||||
|
||||
Companion JSON files exist for Studio and tooling, but they do not replace the contract inside `assets.pa`.
|
||||
|
||||
## 5. Why is determinism so important?
|
||||
|
||||
Because the packer is not just a converter.
|
||||
It is part of the contract chain between authoring, Studio, shipping, and runtime.
|
||||
|
||||
If equivalent inputs can produce different outputs accidentally, then:
|
||||
|
||||
- debugging becomes harder;
|
||||
- caching becomes unreliable;
|
||||
- artifact review gets noisy;
|
||||
- runtime compatibility becomes more fragile.
|
||||
|
||||
That is why the packer decisions keep preferring:
|
||||
|
||||
- explicit declaration over inference;
|
||||
- stable identity over convenience;
|
||||
- canonical serialization over incidental serializer behavior;
|
||||
- preview/apply over silent mutation.
|
||||
|
||||
## How To Read The Packer Specs
|
||||
|
||||
Use this order:
|
||||
|
||||
1. domain and boundary
|
||||
2. workspace and identity
|
||||
3. asset declaration
|
||||
4. build artifacts
|
||||
5. diagnostics and Studio integration
|
||||
6. versioning and trust
|
||||
|
||||
That sequence moves from “what the packer is” to “how it behaves” to “how it stays safe over time”.
|
||||
@@ -1,118 +0,0 @@
|
||||
# Pack Wizard: Summary, Validation, and Pack Execution
|
||||
|
||||
## Original Problem
|
||||
|
||||
The Studio-side wizard was already accepted as a shell over packer-owned operations, but the packer side still needed one coherent story for:
|
||||
|
||||
1. what `summary` means;
|
||||
2. what `validation` means;
|
||||
3. how `packWorkspace(...)` executes without trusting stale UI state or live filesystem rereads.
|
||||
|
||||
The historical agenda, decisions, and PRs solved this in slices.
|
||||
This document keeps the final model in one place.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The first-wave `Pack Wizard` contract is phase-based and fully packer-owned:
|
||||
|
||||
1. `summary` is a fast snapshot-backed preflight view;
|
||||
2. `validation` is a snapshot-backed gate over the same active pack set;
|
||||
3. `packWorkspace(...)` is the only artifact-emitting wizard operation;
|
||||
4. execution reruns the gate on a fresh frozen snapshot;
|
||||
5. outputs are staged before promotion into final `build/` locations.
|
||||
|
||||
The active pack set is always:
|
||||
|
||||
`registered + included in build`
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Summary
|
||||
|
||||
`summary` is not a build preview.
|
||||
It is a quick packer-owned view of the current active pack set.
|
||||
|
||||
First-wave payload:
|
||||
|
||||
- total included asset count;
|
||||
- one per-asset list with:
|
||||
- `assetId`
|
||||
- `assetName`
|
||||
- `assetFamily`
|
||||
- `minArtifactCount`
|
||||
- `maxArtifactCount`
|
||||
- `lastModified`
|
||||
|
||||
### 2. Validation
|
||||
|
||||
`validation` evaluates the same pack set as `summary`, but its job is to answer a different question:
|
||||
|
||||
Can packing begin?
|
||||
|
||||
First-wave rule:
|
||||
|
||||
- only `blocking` diagnostics fail validation;
|
||||
- warnings are visible elsewhere, but they are not part of the first validation gate contract.
|
||||
|
||||
Primary payload:
|
||||
|
||||
- one per-asset list containing only assets with blocking diagnostics.
|
||||
|
||||
### 3. Pack Execution
|
||||
|
||||
`packWorkspace(...)` is a write-lane operation.
|
||||
It does not trust that earlier summary or validation responses are still current.
|
||||
|
||||
The first-wave execution path is:
|
||||
|
||||
1. create a fresh execution snapshot;
|
||||
2. rerun the gate on that snapshot;
|
||||
3. materialize outputs from frozen in-memory inputs;
|
||||
4. write to `build/.staging/<operation-id>/`;
|
||||
5. promote to final `build/` outputs only after coherent success.
|
||||
|
||||
### 4. Result Semantics
|
||||
|
||||
The final result must distinguish:
|
||||
|
||||
- gate failure before emission;
|
||||
- execution/materialization failure;
|
||||
- persistence/promotion failure;
|
||||
- successful publication.
|
||||
|
||||
Studio should be able to render `Packing` and `Result` from packer-owned outcome semantics alone.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why green validation is not enough
|
||||
|
||||
Validation may have been green a few seconds earlier.
|
||||
If the workspace changes before pack execution begins, the packer still must rerun the gate on a fresh frozen snapshot.
|
||||
|
||||
That protects the operation from:
|
||||
|
||||
- stale UI assumptions;
|
||||
- filesystem drift;
|
||||
- accidental emission from no-longer-valid inputs.
|
||||
|
||||
### Example: Why summary excludes unregistered assets
|
||||
|
||||
The wizard is a pack-set workflow, not a generic workspace inspection screen.
|
||||
Unregistered or excluded assets may matter to other tooling, but they are not explicit summary items in the first-wave wizard contract.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating `summary` as if it were an emitted-artifact preview.
|
||||
- Running validation over a broader set than `registered + included in build`.
|
||||
- Letting non-blocking warnings fail the first-wave validation gate.
|
||||
- Reading live filesystem bytes after frozen execution materialization has started.
|
||||
- Publishing final `build/` outputs before the operation has reached a coherent success point.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../studio/learn/pack-wizard-shell.md`](../../studio/learn/pack-wizard-shell.md)
|
||||
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
@@ -1,88 +0,0 @@
|
||||
# Runtime Ownership and Studio Boundary
|
||||
|
||||
## Original Problem
|
||||
|
||||
Once the packer stopped being just a set of direct filesystem helpers, the repository needed a clear answer for three things:
|
||||
|
||||
1. who owns operational asset semantics;
|
||||
2. how concurrent reads and writes stay coherent;
|
||||
3. how Studio consumes packer state without duplicating domain logic.
|
||||
|
||||
Without that boundary, the system would drift into split-brain behavior between packer services and Studio UI code.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The packer is the semantic owner of operational asset state.
|
||||
Studio is a consumer of packer responses, commands, and events.
|
||||
|
||||
The stable boundary is:
|
||||
|
||||
- filesystem-first authoring workspace;
|
||||
- project-scoped runtime snapshot for reads;
|
||||
- single-writer semantic lane per project for commit-bearing operations;
|
||||
- packer-native observability with causal ordering;
|
||||
- Studio adapters that translate for presentation but do not invent semantics.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Filesystem-First Runtime
|
||||
|
||||
- the workspace on disk remains the durable source of truth;
|
||||
- the runtime snapshot is an operational projection used for coherent reads and write coordination;
|
||||
- divergence between runtime state and filesystem state must become explicit packer state, not silent repair.
|
||||
|
||||
### 2. Concurrency Model
|
||||
|
||||
- `read/read` may run concurrently when both observe one coherent snapshot;
|
||||
- `read/write` must not expose torn intermediate state;
|
||||
- `write/write` on the same project is serialized;
|
||||
- build-bearing operations share the same project-scoped coordination story.
|
||||
|
||||
### 3. Event Ownership
|
||||
|
||||
- packer events are authoritative for lifecycle, progress, and outcomes;
|
||||
- each logical operation carries stable causality through `operation_id` and monotonic `sequence`;
|
||||
- sinks may coalesce noisy progress updates, but terminal lifecycle events remain observable.
|
||||
|
||||
### 4. Studio Adapter Rule
|
||||
|
||||
- Studio may remap packer data into workspace and shell view models;
|
||||
- Studio must not recreate packer summaries, mutation semantics, or reconcile semantics from local heuristics;
|
||||
- adapter code is translational, not semantic-authoritative.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Mutation preview in Studio
|
||||
|
||||
The preview may be rendered in Studio-specific components, but the semantic meaning of:
|
||||
|
||||
- blockers,
|
||||
- warnings,
|
||||
- registry mutations,
|
||||
- filesystem mutations,
|
||||
- final apply outcome
|
||||
|
||||
must still come from the packer.
|
||||
|
||||
### Example: Activity and progress
|
||||
|
||||
If the UI shows a simplified progress bar or activity feed, that is fine.
|
||||
What is not fine is for Studio to infer a successful final outcome without a packer-native terminal event or response.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Rebuilding packer summaries from navigator rows or local filesystem scans.
|
||||
- Treating adapter code as a second owner of mutation or reconcile rules.
|
||||
- Hiding divergence by silently refreshing state without surfacing the transition.
|
||||
- Allowing same-project writes to race because the caller "already validated" earlier.
|
||||
- Collapsing event causality into UI-local state that cannot be replayed or tested outside Studio.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md)
|
||||
@@ -1,116 +0,0 @@
|
||||
# Tile Bank Packing Contract
|
||||
|
||||
## Original Problem
|
||||
|
||||
After the generic pack execution boundary was closed, `tile bank` still lacked one explicit producer contract.
|
||||
|
||||
The repository needed to settle:
|
||||
|
||||
1. how selected tile artifacts become one packed payload;
|
||||
2. how palette identity is declared and normalized;
|
||||
3. which runtime fields are derived for `AssetEntry`;
|
||||
4. which structural problems block packing before byte emission.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The first-wave `tile bank` producer contract is:
|
||||
|
||||
1. one canonical `TILES/indexed_v1` payload per asset;
|
||||
2. `1 artifact = 1 tile`;
|
||||
3. artifacts are normalized by explicit `artifacts[*].index`;
|
||||
4. the emitted sheet is fixed at `256 x 256` and row-major;
|
||||
5. tile pixels are packed `u4`;
|
||||
6. bank palettes are emitted as `RGB565` `u16`;
|
||||
7. palette declarations use explicit `{ index, palette }`;
|
||||
8. structural diagnostics are produced early in walker/materialization and therefore participate in validation.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Payload Shape
|
||||
|
||||
The payload is not a concatenation of artifact-local binaries.
|
||||
It is one canonical bank raster:
|
||||
|
||||
1. packed `u4` pixel indices for the full sheet;
|
||||
2. one `64 * 16 * 2` palette block.
|
||||
|
||||
### 2. Artifact and Tile Identity
|
||||
|
||||
- artifacts are normalized by ascending declared `index`;
|
||||
- `tile_id` matches the normalized artifact index;
|
||||
- placement is row-major in the fixed sheet;
|
||||
- v1 capacities depend on `tile_size`:
|
||||
- `8 -> 1024`
|
||||
- `16 -> 256`
|
||||
- `32 -> 64`
|
||||
|
||||
### 3. Palette Contract
|
||||
|
||||
- palette identity is semantic, not positional;
|
||||
- ordering is ascending numeric `index`, never raw list order;
|
||||
- any tile may be rendered with any bank palette at runtime;
|
||||
- palette selection is a draw-time concern, not an embedded per-tile payload field.
|
||||
|
||||
### 4. Metadata Contract
|
||||
|
||||
`AssetEntry.metadata` keeps runtime-required fields readable at the root while preserving segmented subtrees:
|
||||
|
||||
- `output.metadata -> metadata`
|
||||
- `output.codec_configuration -> metadata.codec`
|
||||
- `output.pipeline -> metadata.pipeline`
|
||||
|
||||
For tile banks, that means root readability for values such as:
|
||||
|
||||
- `tile_size`
|
||||
- `width`
|
||||
- `height`
|
||||
- `palette_count`
|
||||
|
||||
### 5. Validation Boundary
|
||||
|
||||
Tile-bank structural issues belong in the walker/materialization path, not in a late pack-only surprise phase.
|
||||
|
||||
Blocking conditions include:
|
||||
|
||||
- duplicate artifact indices;
|
||||
- gaps in normalized artifact indices;
|
||||
- fixed-sheet overflow;
|
||||
- missing palettes;
|
||||
- palette count above `64`;
|
||||
- malformed palette declarations;
|
||||
- missing required metadata;
|
||||
- normalization failure.
|
||||
|
||||
Fragile tile indices are warnings in the first wave, not blockers by themselves.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why palette index must be explicit
|
||||
|
||||
If palette identity depends on array position, a harmless editorial reorder can silently change runtime meaning.
|
||||
|
||||
Using `{ index, palette }` makes semantic identity reviewable and stable.
|
||||
|
||||
### Example: Why validation must see tile-bank structure early
|
||||
|
||||
If duplicate artifact indices are discovered only during final byte emission, the wizard reaches `Packing` too late.
|
||||
The correct behavior is for validation to surface the blocker before emission begins, and for pack execution to rerun that same gate on a fresh execution snapshot.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating artifact declaration order as semantic tile identity.
|
||||
- Packing per-artifact fragments instead of one canonical sheet.
|
||||
- Embedding palette choice per tile in the packed payload.
|
||||
- Flattening all metadata into one ambiguous map.
|
||||
- Discovering tile-bank blockers only during late byte emission.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
|
||||
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
|
||||
- Related learn:
|
||||
- [`./mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)
|
||||
@@ -1,68 +0,0 @@
|
||||
# Packer Pull Requests
|
||||
|
||||
This directory contains self-contained packer change proposals for review.
|
||||
|
||||
Current retained set:
|
||||
|
||||
- none
|
||||
|
||||
The previous execution wave has already been consolidated into [`../learn/`](../learn/) and propagated into [`../specs/`](../specs/).
|
||||
|
||||
## Purpose
|
||||
|
||||
A pull request document packages a packer change as an executable plan before final integration.
|
||||
|
||||
Use this directory when a change:
|
||||
|
||||
- touches multiple documents or code paths,
|
||||
- changes packer architecture or semantics,
|
||||
- needs explicit acceptance criteria,
|
||||
- affects diagnostics, build outputs, registry rules, or shipper boundaries,
|
||||
- should be reviewed before editing the final normative corpus or implementation.
|
||||
|
||||
## Required Properties
|
||||
|
||||
Every pull request document must be self-contained.
|
||||
|
||||
A reviewer should be able to understand:
|
||||
|
||||
- the problem,
|
||||
- the target state,
|
||||
- the execution method,
|
||||
- the acceptance bar,
|
||||
- and the validation surface.
|
||||
|
||||
## Required Sections
|
||||
|
||||
Each packer pull request should include, at minimum:
|
||||
|
||||
1. Briefing
|
||||
2. Target
|
||||
3. Method
|
||||
4. Acceptance Criteria
|
||||
5. Tests or Validation
|
||||
|
||||
Recommended additional sections:
|
||||
|
||||
6. Motivation
|
||||
7. Scope
|
||||
8. Non-Goals
|
||||
9. Affected Documents
|
||||
10. Open Questions
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Keep the proposal self-contained and reviewable.
|
||||
- Separate architectural reasoning from implementation detail.
|
||||
- Make packer outputs and contracts explicit.
|
||||
- Do not smuggle unresolved product or architecture choices into implementation steps.
|
||||
- If a required decision is missing, stop and raise it instead of guessing.
|
||||
|
||||
## Review Rule
|
||||
|
||||
A pull request may plan code and spec consequences, but it must not replace a missing decision record.
|
||||
|
||||
## Production Sequence
|
||||
|
||||
When a new execution wave starts, add only the PRs that still represent pending work.
|
||||
Do not repopulate this directory with already-absorbed historical implementation slices.
|
||||
@@ -56,12 +56,12 @@ If a spec edit would require guessing an unresolved design choice, stop and surf
|
||||
|
||||
The current packer core corpus is:
|
||||
|
||||
1. [`1. Domain and Artifact Boundary Specification.md`](./1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
2. [`2. Workspace, Registry, and Asset Identity Specification.md`](./2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
3. [`3. Asset Declaration and Virtual Asset Contract Specification.md`](./3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
4. [`4. Build Artifacts and Deterministic Packing Specification.md`](./4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
5. [`5. Diagnostics, Operations, and Studio Integration Specification.md`](./5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
6. [`6. Versioning, Migration, and Trust Model Specification.md`](./6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
|
||||
1. [`1. Domain and Artifact Boundary Specification.md`](1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
2. [`2. Workspace, Registry, and Asset Identity Specification.md`](2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
3. [`3. Asset Declaration and Virtual Asset Contract Specification.md`](3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
4. [`4. Build Artifacts and Deterministic Packing Specification.md`](4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
5. [`5. Diagnostics, Operations, and Studio Integration Specification.md`](5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
6. [`6. Versioning, Migration, and Trust Model Specification.md`](6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
|
||||
|
||||
## Reading Order
|
||||
|
||||
+3
-3
@@ -26,9 +26,9 @@ This specification stabilizes:
|
||||
|
||||
This specification extends:
|
||||
|
||||
- [`1. Studio Shell and Workspace Layout Specification.md`](./1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- [`2. Studio UI Foundations Specification.md`](./2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
- [`3. Studio Components Module Specification.md`](./3.%20Studio%20Components%20Module%20Specification.md)
|
||||
- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
- [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
|
||||
|
||||
For packer-facing semantics, this specification must align with:
|
||||
|
||||
@@ -50,10 +50,10 @@ If a spec edit would require guessing unresolved UI behavior, stop and surface t
|
||||
|
||||
The current Studio core corpus is:
|
||||
|
||||
1. [`1. Studio Shell and Workspace Layout Specification.md`](./1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
2. [`2. Studio UI Foundations Specification.md`](./2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
3. [`3. Studio Components Module Specification.md`](./3.%20Studio%20Components%20Module%20Specification.md)
|
||||
4. [`4. Assets Workspace Specification.md`](./4.%20Assets%20Workspace%20Specification.md)
|
||||
1. [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
2. [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
3. [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
|
||||
4. [`4. Assets Workspace Specification.md`](4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Reading Order
|
||||
|
||||
@@ -1,118 +0,0 @@
|
||||
# Studio Documentation
|
||||
|
||||
This directory contains the working, planning, normative, and didactic documentation for the `studio` domain.
|
||||
|
||||
`studio` is a standalone domain focused on the UI shell, workspace model, interaction design, and service integration of `prometeu-studio`.
|
||||
|
||||
It follows the same documentary cycle used elsewhere in the repository:
|
||||
|
||||
`agendas -> decisions -> pull-requests -> specs -> learn`
|
||||
|
||||
## Tree
|
||||
|
||||
```text
|
||||
docs/studio/
|
||||
├── agendas/
|
||||
├── decisions/
|
||||
├── learn/
|
||||
├── pull-requests/
|
||||
├── specs/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Current Code Context
|
||||
|
||||
The current `prometeu-studio` application already has a lightweight shell:
|
||||
|
||||
- `MainView` composes the application frame;
|
||||
- `WorkspaceBar` switches between workspaces;
|
||||
- `EditorWorkspace` is the most concrete workspace today;
|
||||
- `Assets` is still a placeholder workspace;
|
||||
- `BuilderWorkspace` exists as an implementation artifact, but Studio UI planning should treat shipping and asset tooling as distinct concerns going forward.
|
||||
|
||||
The first Studio documentation wave should therefore focus on turning the current shell into an intentional UI model instead of adding more placeholders.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
### `agendas/`
|
||||
|
||||
`agendas/` is the staging area for open Studio product and interaction questions.
|
||||
|
||||
Use it to:
|
||||
|
||||
- shape workspace and panel structure,
|
||||
- compare UI interaction models,
|
||||
- decide how Studio consumes services and events,
|
||||
- define what must be visible, staged, or confirmed in the UI.
|
||||
|
||||
When a topic is fully propagated into specs and learn, the corresponding agenda should leave the retained set.
|
||||
|
||||
### `decisions/`
|
||||
|
||||
`decisions/` records closed Studio product and UX decisions before they are fully propagated.
|
||||
|
||||
Use it to:
|
||||
|
||||
- close interaction and architecture choices,
|
||||
- define invariants for UI behavior,
|
||||
- capture what must be implemented in Studio code and service contracts.
|
||||
|
||||
Once their content is fully absorbed into specs and learn, they should not be retained just as historical residue.
|
||||
|
||||
### `pull-requests/`
|
||||
|
||||
`pull-requests/` contains execution plans for Studio changes.
|
||||
|
||||
Use it to:
|
||||
|
||||
- break a UI decision into implementation slices,
|
||||
- separate shell work, workspace work, and service integration work,
|
||||
- define acceptance criteria and validation paths.
|
||||
|
||||
### `specs/`
|
||||
|
||||
`specs/` contains the normative Studio contract.
|
||||
|
||||
Use it to:
|
||||
|
||||
- define shell structure,
|
||||
- document workspace responsibilities,
|
||||
- specify interaction flows,
|
||||
- stabilize event and service integration expectations.
|
||||
|
||||
### `learn/`
|
||||
|
||||
`learn/` contains didactic Studio material.
|
||||
|
||||
Use it to:
|
||||
|
||||
- explain the mental model of the Studio,
|
||||
- document why the UI is structured the way it is,
|
||||
- help future contributors navigate shell, workspaces, and integration boundaries.
|
||||
|
||||
## Recommended Flow
|
||||
|
||||
The preferred Studio documentation flow is:
|
||||
|
||||
1. `agendas/`: open and shape the unresolved UI topic.
|
||||
2. `decisions/`: close the product or interaction choice.
|
||||
3. `pull-requests/`: plan propagation into code and specs.
|
||||
4. `specs/`: integrate the normative Studio contract.
|
||||
5. `learn/`: consolidate the final model in a didactic form.
|
||||
|
||||
## Practical Rule
|
||||
|
||||
- `agendas/` stores currently open Studio questions.
|
||||
- `decisions/` stores only decisions that still need propagation.
|
||||
- `pull-requests/` stores only execution plans for pending work.
|
||||
- `specs/` stores the normative Studio contract.
|
||||
- `learn/` stores teaching-oriented Studio knowledge.
|
||||
|
||||
The current Studio core and first `Assets` workspace wave have already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/).
|
||||
At this moment:
|
||||
|
||||
- `agendas/` retains only topics that are still open;
|
||||
- `decisions/` is empty because the last accepted wave was fully propagated;
|
||||
- `pull-requests/` is empty because the historical execution wave was absorbed into `learn/`.
|
||||
|
||||
If implementation exposes a missing UI or interaction decision, stop and return to `agendas/` or `decisions/`.
|
||||
@@ -1,165 +0,0 @@
|
||||
# Palette Management in Studio Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how palettes should be presented, identified, edited, and persisted in Studio without blurring the boundary between Studio UX ownership and packer data ownership.
|
||||
|
||||
This agenda is intentionally scoped to the `tile bank` form session.
|
||||
|
||||
It does not define a universal Studio pattern for every asset family that may expose previewable inputs.
|
||||
|
||||
## Problem
|
||||
|
||||
For `tile bank`, each `*.png` file in the asset should be treated as one tile, and each tile brings along a palette extracted during cache construction.
|
||||
|
||||
That extracted palette is part of the bank input model even if the developer did not author a separate palette document by hand.
|
||||
|
||||
In addition, the developer may add more palettes deliberately, up to a maximum of `64` palettes per bank.
|
||||
|
||||
Without a Studio decision for how those palette sources are presented and selected, implementation will guess at least one of the following incorrectly:
|
||||
|
||||
- whether extracted tile palettes are first-class selectable resources or only an implementation detail;
|
||||
- how the user distinguishes tile-derived palettes, favorite palettes, and asset palettes;
|
||||
- how the `up to 64 palettes` constraint is enforced and explained in the UI;
|
||||
- whether default color loading means a palette starts as a full `16`-color color-key-backed candidate set and is then curated by the developer;
|
||||
- whether Studio writes palette changes directly or routes them through packer.
|
||||
|
||||
## Context
|
||||
|
||||
The current Studio baseline already establishes a few useful constraints:
|
||||
|
||||
- the selected-asset view must expose `Inputs / Preview`, and palettes are explicitly listed as previewable materials in [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md);
|
||||
- the workspace should help the user inspect real project materials rather than force raw JSON or filesystem inspection;
|
||||
- Studio should not invent persistence rules locally when packer already owns authoritative asset state and mutation flows.
|
||||
|
||||
The product direction discussed so far is more concrete than a generic palette browser:
|
||||
|
||||
- every `*.png` input of a `tile bank` is one tile;
|
||||
- each tile yields one extracted palette during cache construction, replacing the older mental model of standalone `file.palette.json` sidecars;
|
||||
- each bank may integrate at most `64` palettes;
|
||||
- each palette contains `16` colors and should load with a default color-key baseline;
|
||||
- the developer should be able to inspect palettes coming from at least three sources:
|
||||
- palettes extracted from tiles;
|
||||
- favorite palettes;
|
||||
- asset palettes;
|
||||
- from that combined candidate set, the developer chooses which palettes become part of the bank.
|
||||
|
||||
What remains open is not the existence of palette management, but the Studio interaction model around this curation flow.
|
||||
|
||||
The current discussion has also converged on a simpler first-wave UI shape:
|
||||
|
||||
- the left side should use a `transfer list` with custom palette rendering;
|
||||
- candidate items should show the palette swatch plus stacked source icons when the same palette matches multiple origins;
|
||||
- the bank selection must stay within `1..64` selected palettes;
|
||||
- the right side should expose a compact tile-preview panel with:
|
||||
- a file/tile selector at the top;
|
||||
- the tile preview in the middle;
|
||||
- the applied palette strip at the bottom.
|
||||
|
||||
That shape should be treated as `tile bank`-specific.
|
||||
|
||||
Other asset families may need different form sessions and different preview/application models.
|
||||
|
||||
## Current Code Context
|
||||
|
||||
Normative Studio docs already cover shell structure, selected-asset details, and preview expectations, but there is no dedicated Studio decision for palette lifecycle in `tile bank`.
|
||||
|
||||
That means the shell can host palette management, but the product model for palette-source aggregation, curation, and bank admission is still open.
|
||||
|
||||
## Options
|
||||
|
||||
1. Treat extracted tile palettes as implicit data only, and let the bank integrate them automatically without explicit curation.
|
||||
2. Treat the bank palette set as an asset-scoped curated selection built from multiple palette sources, with Studio orchestrating selection and packer owning persistence.
|
||||
3. Treat palettes as a fully Studio-owned library/workspace with direct local editing and direct persistence.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Automatic integration is cheap, but it removes deliberate bank curation, hides the `64`-palette budget, and makes it harder to reason about favorites, reusable palettes, and intentional bank composition.
|
||||
2. An asset-scoped curated selection aligns with the concrete bank model: the developer sees candidate palettes from tiles, favorites, and asset-level sources, then chooses which ones enter the bank. The tradeoff is that the Studio must explain source, capacity, and duplicate/conflict behavior clearly.
|
||||
3. A fully Studio-owned palette workspace may look flexible, but it duplicates persistence rules, risks divergence from packer/cache construction, and creates a second authority for bank composition.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adopt the asset-scoped curated-selection model.
|
||||
|
||||
Studio should treat palette management as a first-class `tile bank` workflow, but not as a new independent persistence authority.
|
||||
|
||||
### Baseline Direction
|
||||
|
||||
- the palette admission surface should belong to the `tile bank` asset workflow;
|
||||
- Studio should aggregate candidate palettes from tile-derived extraction, favorites, and asset palettes into one curation surface;
|
||||
- the left side should use a custom-rendered `transfer list` to move palettes into or out of the bank selection;
|
||||
- the user should explicitly choose which palettes enter the bank, with a fixed `1..64` selected range;
|
||||
- each candidate palette should expose its source and stable identity clearly enough for inspection and deduplication decisions;
|
||||
- packer should remain authoritative for extraction, identity, validation, and persistence;
|
||||
- Studio should own the curation UX, including selection state, tile preview state, capacity feedback, and staged mutation review.
|
||||
|
||||
### First-Wave Scope Recommendation
|
||||
|
||||
The first wave should prioritize a management-oriented bank-composition experience:
|
||||
|
||||
- list tile-derived palettes explicitly in the selected `tile bank` asset details;
|
||||
- allow inspection of each palette's `16` colors with the default color-key baseline visible;
|
||||
- aggregate candidate palettes from the supported sources into one transfer-list surface;
|
||||
- render each palette item with:
|
||||
- stacked source icons when the same palette matches multiple origins;
|
||||
- a `16`-swatch horizontal palette strip;
|
||||
- allow the user to move palettes from the candidate side into the bank `selected` side, with a visible `1..64` constraint;
|
||||
- expose a compact preview panel on the right side with:
|
||||
- a tile/file combobox at the top;
|
||||
- a tile preview surface in the middle;
|
||||
- a palette strip at the bottom representing the palette currently applied in the preview;
|
||||
- render the chosen tile preview by applying the currently previewed selected palette to the tile's index matrix;
|
||||
- defer broad standalone palette-authoring workflows until the bank-composition and persistence contract is closed.
|
||||
|
||||
### Preview-State Baseline
|
||||
|
||||
The first wave should keep preview behavior simple.
|
||||
|
||||
The palette transfer list defines the bank's `selected palettes`.
|
||||
|
||||
The right-side preview panel should always render one of the selected palettes, with the following baseline:
|
||||
|
||||
- when the `selected palettes` set is first created or rebuilt, the first selected palette is used by default in the preview;
|
||||
- clicking a palette in the `selected` side updates the palette currently shown in the preview;
|
||||
- changing the previewed palette must not reorder or otherwise mutate the bank selection by itself;
|
||||
- the preview must always use a palette that belongs to the current `selected palettes` set;
|
||||
- if the currently previewed palette is removed, the preview falls back to the first remaining selected palette.
|
||||
|
||||
### Why This Direction
|
||||
|
||||
This keeps the Studio honest about its role.
|
||||
|
||||
The Studio should make bank palette composition understandable and operationally safe, but it should not silently become the source of truth for extraction logic or persisted bank data.
|
||||
|
||||
It also keeps the Studio honest about family-specific UX.
|
||||
|
||||
`Tile bank` has a concrete palette-composition workflow tied to tile index matrices and palette admission limits.
|
||||
|
||||
That does not imply that `audio`, `text`, or other asset families should inherit the same transfer-list and active-preview interaction model.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. How should Studio detect and present duplicate or near-equivalent palettes across tile-derived, favorite, and asset-level sources?
|
||||
2. Are favorites project-scoped references to existing palettes, or can they diverge into editable copies before bank admission?
|
||||
3. What is the canonical user-facing identity of a candidate palette in Studio: source bucket plus logical name, file path, extraction origin tile, stable id, or a combination?
|
||||
4. Should extracted tile palettes always enter the candidate set automatically, or can the developer suppress some of them before curation?
|
||||
5. Should clicking a palette on the `selected` side be the only interaction needed to change the previewed palette in the first wave?
|
||||
6. Which palette operations are read-only in the first wave, and which require staged preview/apply treatment?
|
||||
7. Which parts of this interaction model should remain explicitly `tile bank`-specific, and which parts are reusable Studio form-session primitives?
|
||||
8. Does the first release need only an asset-scoped `tile bank` section, or also a project-level palette browser for discovery and favorites management?
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this agenda into a `decision` that closes four points:
|
||||
|
||||
1. the palette ownership boundary between Studio and packer;
|
||||
2. the source model for candidate palettes in `tile bank`;
|
||||
3. the first-wave asset-scoped `transfer list` UX and `1..64` capacity behavior;
|
||||
4. the right-side preview-panel behavior for tile/file selection, tile rendering, and palette-strip display;
|
||||
5. the boundary between `tile bank`-specific form-session behavior and reusable Studio primitives;
|
||||
6. the minimum mutation model for preview, apply, favorites, and cross-asset visibility.
|
||||
@@ -1,50 +0,0 @@
|
||||
# Studio Agendas
|
||||
|
||||
This directory contains active Studio discussion agendas.
|
||||
|
||||
Active agendas:
|
||||
|
||||
- [`Palette Management in Studio Agenda.md`](./Palette%20Management%20in%20Studio%20Agenda.md)
|
||||
|
||||
Closed Studio agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue.
|
||||
|
||||
## Purpose
|
||||
|
||||
An agenda exists to drive a decision.
|
||||
|
||||
Use an agenda when:
|
||||
|
||||
- the Studio UI topic is still open,
|
||||
- multiple interaction models are possible,
|
||||
- the team still needs tradeoffs and a recommendation,
|
||||
- implementation would otherwise guess shell or UX behavior.
|
||||
|
||||
## Expected Format
|
||||
|
||||
A Studio agenda should usually include:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Purpose
|
||||
4. Domain Owner
|
||||
5. Current Code Context
|
||||
6. Options
|
||||
7. Tradeoffs
|
||||
8. Recommendation
|
||||
9. Open Questions
|
||||
10. Expected Follow-up
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Keep the document centered on unresolved Studio behavior.
|
||||
- Anchor the discussion in the actual `prometeu-studio` shell and workspaces.
|
||||
- Distinguish clearly between shell decisions, workspace decisions, and service-integration decisions.
|
||||
- Prefer concrete interaction tradeoffs over generic design commentary.
|
||||
|
||||
## Exit Rule
|
||||
|
||||
An agenda should leave the active set when:
|
||||
|
||||
- the main UX tradeoffs are understood,
|
||||
- a recommendation is ready to adopt,
|
||||
- and the topic is ready to become a decision record.
|
||||
@@ -1,49 +0,0 @@
|
||||
# Studio Decisions
|
||||
|
||||
This directory contains Studio decision records that still need propagation.
|
||||
|
||||
Current retained set:
|
||||
|
||||
- none
|
||||
|
||||
The current Studio decision wave has already been consolidated into:
|
||||
|
||||
- normative specifications under [`../specs/`](../specs/)
|
||||
- didactic material under [`../learn/`](../learn/)
|
||||
|
||||
## Purpose
|
||||
|
||||
A Studio decision record bridges UI discussion and implementation.
|
||||
|
||||
Use this directory to capture:
|
||||
|
||||
- what Studio behavior was chosen,
|
||||
- why that interaction model was preferred,
|
||||
- what constraints now apply to the shell and workspaces,
|
||||
- what specs, plans, and code paths must be updated.
|
||||
|
||||
## Expected Format
|
||||
|
||||
A Studio decision should usually include:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Date or Cycle
|
||||
4. Context
|
||||
5. Decision
|
||||
6. Invariants and Constraints
|
||||
7. Explicit Non-Decisions
|
||||
8. Propagation Targets
|
||||
9. Validation Notes or Examples
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- State the adopted Studio behavior early and clearly.
|
||||
- Keep the tone stable and implementation-oriented.
|
||||
- Record interaction constraints explicitly.
|
||||
- Point to exact specs, plans, or UI surfaces that need propagation.
|
||||
|
||||
## Implementation Rule
|
||||
|
||||
If Studio code work reveals a missing decision, do not guess the UX contract.
|
||||
Return the issue to agenda or decision review.
|
||||
@@ -1,56 +0,0 @@
|
||||
# Studio Learn
|
||||
|
||||
This directory contains didactic Studio knowledge.
|
||||
|
||||
## Purpose
|
||||
|
||||
`learn/` exists to teach the Studio model, not merely to store old discussion output.
|
||||
|
||||
Use it to:
|
||||
|
||||
- explain why the Studio shell is structured the way it is,
|
||||
- connect UI decisions to practical implementation,
|
||||
- document common integration pitfalls,
|
||||
- help future contributors navigate the workspaces and background event model.
|
||||
|
||||
## What Belongs Here
|
||||
|
||||
A Studio `learn` artifact should usually include:
|
||||
|
||||
1. the original UX or architecture problem,
|
||||
2. the decision that resolved it,
|
||||
3. the implemented or specified final model,
|
||||
4. practical examples or flows,
|
||||
5. common mistakes and warnings,
|
||||
6. links to relevant specs and plans.
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Prefer didactic structure over historical accumulation.
|
||||
- Explain why the Studio model exists, not only what it is.
|
||||
- Keep terminology aligned with Studio specs.
|
||||
- Refactor older material when the directory stops feeling like a clear learning path.
|
||||
|
||||
## Refactor Rule
|
||||
|
||||
This directory should be periodically reorganized for better presentation.
|
||||
|
||||
If content grows, prefer:
|
||||
|
||||
- thematic grouping,
|
||||
- overview documents,
|
||||
- explicit learning paths,
|
||||
- consolidation of duplicated explanations.
|
||||
|
||||
## Current Learning Path
|
||||
|
||||
Start here:
|
||||
|
||||
1. [`mental-model-studio-shell.md`](./mental-model-studio-shell.md)
|
||||
2. [`mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md)
|
||||
3. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
|
||||
4. [`assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)
|
||||
5. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
|
||||
6. [`bank-composition-editor.md`](./bank-composition-editor.md)
|
||||
7. [`pack-wizard-shell.md`](./pack-wizard-shell.md)
|
||||
8. [`project-scoped-state-and-activity.md`](./project-scoped-state-and-activity.md)
|
||||
@@ -1,88 +0,0 @@
|
||||
# Assets Workspace Execution Wave
|
||||
|
||||
## Original Problem
|
||||
|
||||
The first `Assets` workspace wave solved many UI problems in small execution slices:
|
||||
|
||||
- workspace foundation;
|
||||
- asset navigator;
|
||||
- selected-asset details;
|
||||
- activity, progress, and logs;
|
||||
- staged mutations;
|
||||
- event-driven refactor;
|
||||
- package and subscription boundaries.
|
||||
|
||||
That historical sequence was useful while implementation was in flight, but it became a poor learning surface.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The stable Studio direction for `Assets` is:
|
||||
|
||||
1. the workspace is asset-first, not file-first;
|
||||
2. the workspace is event-driven, not refresh-heavy;
|
||||
3. composition, projection, and rendering are separated;
|
||||
4. details sections update independently instead of forcing whole-panel rebuilds;
|
||||
5. mutation review is preview-first;
|
||||
6. the shell reflects operational lifecycle without taking over workspace-local reasoning.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Workspace Foundation
|
||||
|
||||
- `Assets` is a real workspace, not a placeholder;
|
||||
- workspace state is explicit about loading, empty, error, and ready conditions;
|
||||
- selection is stable by asset identity rather than by transient row position.
|
||||
|
||||
### 2. Navigator and Details Split
|
||||
|
||||
- the left side owns navigation and projection;
|
||||
- the main area teaches the selected asset in a fixed didactic order;
|
||||
- navigator updates and details updates must not require a workspace-wide redraw by default.
|
||||
|
||||
### 3. Event-Driven Ownership
|
||||
|
||||
- local UI change flows through typed workspace events;
|
||||
- component-scoped subscriptions replace root-owned redraw logic;
|
||||
- structural sync and local projection updates stay distinct.
|
||||
|
||||
### 4. Operational Surfaces
|
||||
|
||||
- activity belongs to the shell timeline;
|
||||
- progress belongs both to the current workspace flow and the broader shell context;
|
||||
- textual logs are supporting drill-down, not the main explanation surface.
|
||||
|
||||
### 5. Mutation Review
|
||||
|
||||
- preview is the default review surface for sensitive actions;
|
||||
- blockers, warnings, and safe fixes remain semantically separate;
|
||||
- modal confirmation is reserved for high-risk commit boundaries.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why the root should not own every redraw
|
||||
|
||||
If one asset row changes because its diagnostics changed, the correct response is a row-scoped update.
|
||||
Rebuilding navigator, details, and unrelated controls teaches the wrong ownership model and makes the UI harder to reason about.
|
||||
|
||||
### Example: Why the shell still needs activity
|
||||
|
||||
Mutation review happens inside the workspace.
|
||||
But lifecycle milestones such as `preview ready`, `action applied`, or `action failed` still matter at shell scope because they are part of the user's project timeline.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating `Assets` as a filesystem explorer with extra badges.
|
||||
- Using `refresh()` as the default answer to local UI state changes.
|
||||
- Letting details sections depend on a monolithic selected-asset redraw.
|
||||
- Using logs as the primary explanation surface for mutations.
|
||||
- Publishing shell activity without keeping workspace-local review visible.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
|
||||
- [`./mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
|
||||
- [`./mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md)
|
||||
@@ -1,126 +0,0 @@
|
||||
# Bank Composition Editor
|
||||
|
||||
## Original Problem
|
||||
|
||||
`Bank Composition` needed to become a real editor inside `Asset Details` without collapsing into any of these bad outcomes:
|
||||
|
||||
- direct binding to raw snapshot or manifest shapes;
|
||||
- overgeneric UI components before the first section existed;
|
||||
- family-specific rules hidden inside visual controls;
|
||||
- direct Studio writes to `asset.json`;
|
||||
- public bus chatter for every local section interaction.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The first-wave `Bank Composition` model is:
|
||||
|
||||
1. Studio owns a DTO projection boundary for the section;
|
||||
2. the section shell lands early and follows the existing staged-edit rhythm;
|
||||
3. dual-list and capacity-meter components stay intentionally dumb;
|
||||
4. one section-scoped coordinator around `StudioFormSession<BankCompositionDraft>` owns orchestration;
|
||||
5. public workspace-bus events stay minimal and notification-oriented;
|
||||
6. `apply` goes through packer and rebinds from refreshed persisted state.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. DTO Boundary
|
||||
|
||||
The section never consumes raw packer/runtime structures directly.
|
||||
|
||||
It works with Studio-owned DTOs for:
|
||||
|
||||
- `available` rows from current runtime/details state;
|
||||
- `selected` rows from persisted composition state.
|
||||
|
||||
Only non-blocking files enter the `available` DTO projection.
|
||||
|
||||
### 2. Section Shell
|
||||
|
||||
`Bank Composition` is a real `Asset Details` section, not a hidden future placeholder.
|
||||
|
||||
The shell follows the existing staged-edit rhythm:
|
||||
|
||||
- `change`
|
||||
- `apply`
|
||||
- `reset`
|
||||
- `cancel`
|
||||
|
||||
Outside edit mode, it teaches the current persisted state in read-only form.
|
||||
|
||||
### 3. Dumb Components
|
||||
|
||||
Two named components exist for this area:
|
||||
|
||||
- `StudioDualListView<T>`
|
||||
- `StudioAssetCapacityMeter`
|
||||
|
||||
They are intentionally state-driven, not rule-driven.
|
||||
Family-specific transfer, ordering, and capacity semantics do not live inside these components.
|
||||
|
||||
### 4. Section-Scoped Coordinator
|
||||
|
||||
The main orchestration lives in one section-scoped coordinator built around `StudioFormSession<BankCompositionDraft>`.
|
||||
|
||||
That coordinator owns:
|
||||
|
||||
- draft lifecycle;
|
||||
- transfer and reorder effects;
|
||||
- capacity state;
|
||||
- blockers and hints;
|
||||
- apply success and failure handling.
|
||||
|
||||
### 5. WorkspaceBus Boundary
|
||||
|
||||
The public bus surface stays intentionally small.
|
||||
|
||||
First-wave public notifications are about observable state transitions:
|
||||
|
||||
- draft changed;
|
||||
- capacity changed;
|
||||
- apply requested;
|
||||
- apply succeeded;
|
||||
- apply failed.
|
||||
|
||||
Local edit actions remain local to the section coordinator.
|
||||
|
||||
### 6. Persistence Boundary
|
||||
|
||||
Studio does not write `asset.json` directly for `Bank Composition`.
|
||||
|
||||
The write path is:
|
||||
|
||||
1. Studio submits ordered selected files to packer;
|
||||
2. packer validates and persists through `asset.json.artifacts`;
|
||||
3. packer refreshes the minimum runtime/details state;
|
||||
4. Studio rebinds from refreshed persisted state.
|
||||
|
||||
If apply fails, the draft stays alive and the section remains in editing mode.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why the meter must stay dumb
|
||||
|
||||
Tile banks and sound banks may calculate capacity differently.
|
||||
That difference belongs in family policies owned by the coordinator, not in `StudioAssetCapacityMeter`.
|
||||
|
||||
### Example: Why `apply` is not a public bus command
|
||||
|
||||
External observers may care that apply was requested or failed.
|
||||
They do not need to own the local section command sequence for `moveUp`, `moveDown`, `reset`, or `cancel`.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Binding section UI directly to raw snapshot rows or raw manifest shape.
|
||||
- Hiding bank-family rules inside `StudioDualListView<T>` or the capacity meter.
|
||||
- Creating a second staged-edit session model parallel to `StudioFormSession`.
|
||||
- Turning every local section action into a public workspace-bus event.
|
||||
- Writing `asset.json` directly from Studio instead of routing through packer.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)
|
||||
@@ -1,128 +0,0 @@
|
||||
# Mental Model: Asset Mutations
|
||||
|
||||
## The Problem
|
||||
|
||||
Asset mutations are easy to get wrong in a Studio UI.
|
||||
|
||||
Why?
|
||||
|
||||
Because some actions only update registry state, while others change the physical workspace.
|
||||
|
||||
If the Studio hides that difference, users lose trust quickly.
|
||||
|
||||
## The Rule
|
||||
|
||||
Sensitive asset mutations are `preview-first`.
|
||||
|
||||
That is the most important rule.
|
||||
|
||||
The Studio must not perform destructive or relocational asset changes as if they were harmless button clicks.
|
||||
|
||||
## What The User Must Understand Before Apply
|
||||
|
||||
Before applying a mutation, the user should be able to answer:
|
||||
|
||||
- Which assets are affected?
|
||||
- Is this touching only the registry, or also the workspace?
|
||||
- Will something be created, moved, or deleted?
|
||||
- Are there blockers?
|
||||
- Are there warnings?
|
||||
- Is this a safe fix or a risky mutation?
|
||||
|
||||
If the UI cannot answer those questions, the mutation flow is not ready.
|
||||
|
||||
## Why Inline Review Is The Baseline
|
||||
|
||||
The default review surface is an inline staged panel, not a modal.
|
||||
|
||||
That keeps the user anchored in the asset and its surrounding context.
|
||||
|
||||
It lets the user compare:
|
||||
|
||||
- the selected asset,
|
||||
- the diagnostics,
|
||||
- the proposed changes,
|
||||
- and the action consequences
|
||||
|
||||
without bouncing between unrelated windows.
|
||||
|
||||
## Why Modals Still Exist
|
||||
|
||||
Modals are still useful, but only for high-risk final commits.
|
||||
|
||||
Examples:
|
||||
|
||||
- destructive delete;
|
||||
- major relocation;
|
||||
- other strongly irreversible actions.
|
||||
|
||||
The mistake would be using modals as a substitute for review.
|
||||
|
||||
Preview is the review.
|
||||
|
||||
Modal confirmation is only the final safety gate when the risk is high enough.
|
||||
|
||||
## The Most Important Distinction
|
||||
|
||||
The Studio must distinguish:
|
||||
|
||||
- registry impact
|
||||
- workspace impact
|
||||
|
||||
This is one of the most important didactic duties of the asset workspace.
|
||||
|
||||
A user should never have to guess whether a button:
|
||||
|
||||
- merely forgets an asset from management,
|
||||
- or actually deletes or moves files.
|
||||
|
||||
## Blockers, Warnings, and Safe Fixes
|
||||
|
||||
These categories must stay visually and semantically separate.
|
||||
|
||||
They are not interchangeable kinds of “message”.
|
||||
|
||||
- `blockers` stop the apply path;
|
||||
- `warnings` tell the user the action is still meaningful but risky or noteworthy;
|
||||
- `safe fixes` are low-risk corrections and should not be grouped as if they were destructive operations.
|
||||
|
||||
If those three collapse into one list, users stop trusting the flow.
|
||||
|
||||
## Batch Operations
|
||||
|
||||
Batch operations are not just “single asset, repeated many times”.
|
||||
|
||||
They need:
|
||||
|
||||
- an aggregate summary first,
|
||||
- then drill-down detail.
|
||||
|
||||
Without that, the flow becomes unreadable and users either miss risk or abandon the tool.
|
||||
|
||||
## How Activity Fits In
|
||||
|
||||
The preview itself belongs to the workspace.
|
||||
|
||||
But the shell should still reflect lifecycle milestones such as:
|
||||
|
||||
- preview ready;
|
||||
- action applied;
|
||||
- action failed.
|
||||
|
||||
That way the workspace remains the place of review, while the shell keeps the broader operational timeline visible.
|
||||
|
||||
## Common Failure Modes
|
||||
|
||||
Avoid these:
|
||||
|
||||
- destructive apply without preview;
|
||||
- using raw logs as the main explanation surface;
|
||||
- mixing safe fixes with deletes;
|
||||
- showing technical diff data with no user-facing interpretation;
|
||||
- forcing the user into modal-only flows for ordinary review.
|
||||
|
||||
## Read With
|
||||
|
||||
1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
2. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
|
||||
3. [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
@@ -1,119 +0,0 @@
|
||||
# Mental Model: Assets Workspace
|
||||
|
||||
## Why This Workspace Exists
|
||||
|
||||
The `Assets` workspace is not a nicer file browser.
|
||||
|
||||
It exists to make the packer model understandable and usable from the Studio.
|
||||
|
||||
That means the workspace must help a contributor answer questions like:
|
||||
|
||||
- What is the managed asset here?
|
||||
- Where does it live?
|
||||
- Which files belong to it?
|
||||
- What does it produce toward the runtime?
|
||||
- Is it managed, orphaned, preload-marked, or diagnostically unhealthy?
|
||||
|
||||
If the workspace answered those questions only by showing folders and files, it would teach the wrong mental model.
|
||||
|
||||
## The Core Shift
|
||||
|
||||
The key shift is:
|
||||
|
||||
- not `file-first`
|
||||
- but `asset-first`
|
||||
|
||||
An asset may contain many files.
|
||||
|
||||
Those files still matter, but they matter as inputs of an asset, not as the primary unit of identity.
|
||||
|
||||
So the workspace is designed to feel like:
|
||||
|
||||
- a structured asset navigator,
|
||||
- plus a didactic explanation surface for the currently selected asset.
|
||||
|
||||
## Why It Is Still Path-Aware
|
||||
|
||||
`Asset-first` does not mean `filesystem-blind`.
|
||||
|
||||
People still organize projects by directories.
|
||||
|
||||
They still need to know:
|
||||
|
||||
- where the asset root lives;
|
||||
- which broader folder group it belongs to;
|
||||
- how to reason about the project layout.
|
||||
|
||||
That is why the workspace remains `path-aware`.
|
||||
|
||||
The important nuance is:
|
||||
|
||||
- path is supporting context
|
||||
- asset identity is primary
|
||||
|
||||
## What The Left Side Teaches
|
||||
|
||||
The left-side navigator is a custom `Asset Tree` / `Asset Navigator`.
|
||||
|
||||
It teaches the model visually:
|
||||
|
||||
- groups may reflect location or parent folders,
|
||||
- asset nodes are the real unit of navigation,
|
||||
- icons and badges tell the story quickly,
|
||||
- orphan and managed assets can coexist without becoming ambiguous.
|
||||
|
||||
This is better than a raw file tree because the user learns the packer model by looking at the navigation itself.
|
||||
|
||||
## What The Main Area Teaches
|
||||
|
||||
The selected asset view is intentionally structured in a fixed order:
|
||||
|
||||
1. `Summary`
|
||||
2. `Runtime Contract`
|
||||
3. `Inputs / Preview`
|
||||
4. `Diagnostics`
|
||||
5. `Actions`
|
||||
|
||||
That order matters.
|
||||
|
||||
It starts by explaining what the asset is, then what it produces, then what it contains, then what is wrong, and finally what the user can do.
|
||||
|
||||
That is a teaching sequence, not just a layout sequence.
|
||||
|
||||
## Why Preview Matters
|
||||
|
||||
Preview is not decorative.
|
||||
|
||||
Preview is part of how the workspace bridges the conceptual asset model with the real materials inside the project.
|
||||
|
||||
Examples:
|
||||
|
||||
- an image bank should let the user inspect images and palettes;
|
||||
- an audio asset should let the user inspect sound inputs;
|
||||
- text-like artifacts should be inspectable as text when that helps understanding.
|
||||
|
||||
This makes the workspace feel grounded in real project materials while still preserving an asset-first model.
|
||||
|
||||
## What To Avoid
|
||||
|
||||
Common mistakes:
|
||||
|
||||
- turning the workspace into a raw filesystem explorer with extra badges;
|
||||
- making path the true identity instead of the asset;
|
||||
- showing only diagnostics and forgetting the actual asset model;
|
||||
- treating orphan as if it meant broken;
|
||||
- hiding runtime-facing information behind technical dumps.
|
||||
|
||||
## Practical Read Order
|
||||
|
||||
Read these together:
|
||||
|
||||
1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
2. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
|
||||
3. [`../../packer/learn/mental-model-packer.md`](../../packer/learn/mental-model-packer.md)
|
||||
|
||||
That path explains:
|
||||
|
||||
- what the packer believes,
|
||||
- how the Studio presents it,
|
||||
- and how the user should reason about asset operations.
|
||||
@@ -1,76 +0,0 @@
|
||||
# Studio Events and Components Mental Model
|
||||
|
||||
Two things are meant to stop the Studio from becoming messy as it grows:
|
||||
|
||||
- a typed event model;
|
||||
- a single authoritative control layer.
|
||||
|
||||
These two rules solve different problems, but they reinforce each other.
|
||||
|
||||
## Why a Studio-owned event system?
|
||||
|
||||
Without it, the shell, workspaces, and services begin to call each other directly.
|
||||
|
||||
That usually feels fine at first, because the UI is small. Then the application gains:
|
||||
|
||||
- global activity surfaces;
|
||||
- background operations;
|
||||
- multiple workspaces;
|
||||
- status and progress reporting;
|
||||
- cross-cutting actions such as run or diagnostics.
|
||||
|
||||
At that point, direct references become the path of least resistance and the UI starts coupling itself in ways that are hard to unwind.
|
||||
|
||||
The Studio event system exists to keep event publication explicit and typed.
|
||||
|
||||
## Why both a global bus and workspace buses?
|
||||
|
||||
Because the Studio needs both segregation and shared visibility.
|
||||
|
||||
Workspaces should be able to keep their local activity scoped.
|
||||
The shell should still be able to observe what is happening globally.
|
||||
|
||||
The chosen rule is therefore:
|
||||
|
||||
- each workspace has its own bus;
|
||||
- the Studio has a global bus;
|
||||
- every workspace event is automatically republished to the global bus.
|
||||
|
||||
This means callers do not need to decide when to duplicate publication manually.
|
||||
|
||||
## Why not rely on raw JavaFX controls directly?
|
||||
|
||||
Because raw JavaFX use spreads quickly and creates UI drift.
|
||||
|
||||
When each part of the app consumes JavaFX controls directly, the Studio gradually accumulates:
|
||||
|
||||
- inconsistent naming;
|
||||
- inconsistent styling hooks;
|
||||
- repeated local wrappers;
|
||||
- uneven behavior between screens;
|
||||
- more work each time theme or locale behavior needs to change.
|
||||
|
||||
That is why the Studio uses `prometeu-studio-components` as its visual control layer.
|
||||
|
||||
## Does that mean reimplementing JavaFX?
|
||||
|
||||
No.
|
||||
|
||||
The goal is not to reproduce every JavaFX API.
|
||||
The goal is to expose the Studio-facing API the application actually needs.
|
||||
|
||||
That keeps the control layer:
|
||||
|
||||
- opinionated;
|
||||
- smaller than JavaFX;
|
||||
- aligned with the Studio's own UI dialect.
|
||||
|
||||
## Practical reading rule
|
||||
|
||||
When adding UI code, ask two questions:
|
||||
|
||||
1. Is this communication really an event?
|
||||
2. Is this control part of the Studio's visible dialect?
|
||||
|
||||
If the answer to the first question is yes, it should probably publish a typed Studio event.
|
||||
If the answer to the second question is yes, it should probably come through `prometeu-studio-components`.
|
||||
@@ -1,60 +0,0 @@
|
||||
# Studio Shell Mental Model
|
||||
|
||||
The Studio shell exists to frame workspaces, not to absorb every piece of UI.
|
||||
|
||||
That distinction matters because a lot of early JavaFX applications slowly become a single giant layout where every new concern gets added to the same frame. The shell model chosen here avoids that.
|
||||
|
||||
## What belongs to the shell?
|
||||
|
||||
The shell owns:
|
||||
|
||||
- project entry through a launcher or home surface;
|
||||
- global menus;
|
||||
- fixed workspace navigation;
|
||||
- the workspace host;
|
||||
- the right-side utility surface;
|
||||
- the always-visible run surface.
|
||||
|
||||
The shell does not own the full operating detail of every domain workflow.
|
||||
|
||||
## What belongs to a workspace?
|
||||
|
||||
A workspace owns its main body and its domain-specific detail.
|
||||
|
||||
That includes things like:
|
||||
|
||||
- editor-specific structure;
|
||||
- asset-management views;
|
||||
- debugger and profiler views;
|
||||
- workspace-local logs and detailed operational output.
|
||||
|
||||
This is why the Studio does not define a mandatory single global console as the primary logging model.
|
||||
|
||||
## Why avoid a fully docked shell right now?
|
||||
|
||||
Because the Studio is still proving its topology.
|
||||
|
||||
If docking is introduced too early, the codebase starts solving these problems before the product actually needs them:
|
||||
|
||||
- panel restore rules;
|
||||
- drag-and-drop docking behavior;
|
||||
- focus and lifecycle complexity;
|
||||
- layout persistence;
|
||||
- too many shell-level extension points.
|
||||
|
||||
The structured shell keeps the frame stable without pretending the full IDE model is already known.
|
||||
|
||||
## Why is `Run` always visible?
|
||||
|
||||
Because run is a primary action, not a secondary panel.
|
||||
|
||||
If running the project requires opening a tab first, the shell is hiding one of the most important actions behind navigation friction. The Studio therefore treats `Run` as a persistent shell control.
|
||||
|
||||
## Practical reading rule
|
||||
|
||||
When deciding whether something belongs in the shell or in a workspace, ask:
|
||||
|
||||
> “Is this a Studio-wide framing concern, or is it operational detail of one workspace?”
|
||||
|
||||
If it is framing, it belongs in the shell.
|
||||
If it is operational detail, it probably belongs in the workspace.
|
||||
@@ -1,87 +0,0 @@
|
||||
# Pack Wizard Shell
|
||||
|
||||
## Original Problem
|
||||
|
||||
The `Assets` workspace already had a reserved `Pack` action, but that did not answer the real product question:
|
||||
|
||||
How should Studio behave when the developer wants to pack the current build set?
|
||||
|
||||
The risk was building a visually plausible modal that quietly reimplemented packer semantics or hid the real operational phases.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The stable first-wave rule is:
|
||||
|
||||
`Pack` is a Studio-owned wizard shell over packer-owned operations.
|
||||
|
||||
The wizard is phase-based:
|
||||
|
||||
1. `Summary`
|
||||
2. `Validation`
|
||||
3. `Packing`
|
||||
4. `Result`
|
||||
|
||||
Studio owns presentation and state binding.
|
||||
Packer owns summary, validation, execution, progress, and result semantics.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Workspace-Level Entry Point
|
||||
|
||||
- `Pack` is a workspace action, not a selected-asset action;
|
||||
- the user is operating on the current pack set, not on one asset in isolation.
|
||||
|
||||
### 2. Summary
|
||||
|
||||
- the wizard asks packer for the current build-set summary;
|
||||
- Studio does not count navigator rows and pretend that is the build set;
|
||||
- the canonical runtime artifact is explicitly `assets.pa`.
|
||||
|
||||
### 3. Validation
|
||||
|
||||
- validation runs only on `registered + included in build`;
|
||||
- blocking diagnostics stop the flow before execution;
|
||||
- warnings may be visible, but they do not become blockers unless packer classifies them that way.
|
||||
|
||||
### 4. Packing
|
||||
|
||||
- execution is operational and non-editable;
|
||||
- progress comes from packer-owned progress state or events;
|
||||
- the UI does not simulate progress with timers;
|
||||
- the first wave is non-cancelable.
|
||||
|
||||
### 5. Result
|
||||
|
||||
- the primary summary shows final status, packed asset count, elapsed time, and `assets.pa`;
|
||||
- companion artifacts are supporting detail, not the headline of the result screen;
|
||||
- the UI must distinguish blocked, failed, and successful outcomes.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why validation is a separate phase
|
||||
|
||||
If the wizard jumps straight from summary into execution, the user loses the explicit gate that explains why packing is blocked.
|
||||
Validation exists to make the gate understandable before byte emission begins.
|
||||
|
||||
### Example: Why Studio must not fake progress
|
||||
|
||||
A fake progress bar may look smoother, but it lies about operational ownership.
|
||||
If the packer is the owner of execution semantics, the UI must reflect packer-owned progress honestly.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating pack summary as a local Studio recomputation.
|
||||
- Using one opaque modal state instead of explicit operational phases.
|
||||
- Letting unrelated assets influence wizard validation.
|
||||
- Exposing fake cancel behavior that the packer does not actually support.
|
||||
- Making companion artifacts dominate the main result summary.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md`](../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md)
|
||||
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)
|
||||
@@ -1,57 +0,0 @@
|
||||
# Project-Scoped State and Activity
|
||||
|
||||
## Original Problem
|
||||
|
||||
Some Studio state is global by nature, but some state is clearly tied to one opened project.
|
||||
|
||||
If project-local state is stored as if it were application-global, the shell starts mixing unrelated histories and the project root stops being the obvious home of Studio-owned project data.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The stable direction is:
|
||||
|
||||
1. project-local Studio state lives under `.studio/` inside the project root;
|
||||
2. shell activity is restored and persisted per project;
|
||||
3. persisted activity history is bounded;
|
||||
4. `.studio/` is the reserved root for future project-local Studio settings.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Storage Root
|
||||
|
||||
- each project owns `.studio/`;
|
||||
- new-project scaffolding creates that directory;
|
||||
- `.workspace/` is not the project-local Studio root for this model.
|
||||
|
||||
### 2. Activity Persistence
|
||||
|
||||
- shell activity is loaded when the project opens;
|
||||
- new activity is appended to that project's local history;
|
||||
- history is trimmed to the latest `500` entries.
|
||||
|
||||
### 3. Scope Rule
|
||||
|
||||
- project-local shell history belongs to the project;
|
||||
- launcher-global concerns remain outside this storage path;
|
||||
- future Studio project configuration can live under the same `.studio/` root.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why activity cannot stay application-global
|
||||
|
||||
If two projects have one shared persisted feed, the shell stops teaching the user what happened in the currently opened project.
|
||||
That destroys causality instead of preserving it.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating project activity as if it were launcher-global state.
|
||||
- Mixing unrelated projects into one persisted activity history.
|
||||
- Leaving project-local Studio files in ad hoc roots instead of `.studio/`.
|
||||
- Letting unbounded activity persistence grow without a hard cap.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./mental-model-studio-shell.md`](./mental-model-studio-shell.md)
|
||||
@@ -1,46 +0,0 @@
|
||||
# Studio Pull Requests
|
||||
|
||||
This directory contains executable plans for Studio work.
|
||||
|
||||
Current retained set:
|
||||
|
||||
- none
|
||||
|
||||
The previous Studio execution wave has already been consolidated into [`../learn/`](../learn/) and propagated into [`../specs/`](../specs/).
|
||||
|
||||
## Purpose
|
||||
|
||||
A Studio pull-request or plan artifact packages a decision into an implementable sequence.
|
||||
|
||||
Use it to:
|
||||
|
||||
- separate shell work from workspace work,
|
||||
- describe service and event-lane integration steps,
|
||||
- define acceptance criteria for UI behavior,
|
||||
- make validation and regression risks explicit before code changes.
|
||||
|
||||
## Expected Format
|
||||
|
||||
A Studio plan should usually include:
|
||||
|
||||
1. Briefing
|
||||
2. Objective
|
||||
3. Dependencies
|
||||
4. Scope
|
||||
5. Non-Goals
|
||||
6. Execution Method
|
||||
7. Acceptance Criteria
|
||||
8. Validation
|
||||
9. Affected Artifacts
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Organize by execution sequence, not by brainstorming.
|
||||
- Keep visual design, interaction behavior, and service integration clearly separated.
|
||||
- State what the user should be able to do after the change lands.
|
||||
- Tie the plan back to Studio specs and decisions explicitly.
|
||||
|
||||
## Current Queue
|
||||
|
||||
When a new Studio execution wave starts, add only the plans that still represent pending work.
|
||||
Do not repopulate this directory with already-absorbed historical implementation slices.
|
||||
Reference in New Issue
Block a user