discussion framework migration

This commit is contained in:
2026-03-26 18:45:46 +00:00
parent e78b72f61a
commit 38d8c25bba
90 changed files with 1150 additions and 2585 deletions
-20
View File
@@ -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.
+27 -14
View File
@@ -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
-112
View File
@@ -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/`.
-54
View File
@@ -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.
-53
View File
@@ -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.
-59
View File
@@ -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)
-87
View File
@@ -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)
-68
View File
@@ -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
@@ -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
-118
View File
@@ -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.
-50
View File
@@ -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.
-49
View File
@@ -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.
-56
View File
@@ -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.
-87
View File
@@ -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)
-46
View File
@@ -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.