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
@@ -0,0 +1,116 @@
---
id: AGD-0002
ticket: palette-management-in-studio
title: Palette Management in Studio
status: open
created: 2026-03-26
resolved:
decision:
tags:
- studio
- legacy-import
- palette-management
- tile-bank
- packer-boundary
---
## Pain
Studio already has a retained agenda for palette management in the `tile bank` form session, but that agenda exists only under `docs/studio/agendas/` and therefore sits outside the discussion-framework lifecycle.
Without importing it into `.discussion/`, the canonical discussion surface would lose the still-open Studio question about:
- how candidate palettes are presented;
- how `1..64` palette capacity is enforced and explained;
- how preview and selection behave inside the asset workflow;
- how Studio UX stays separate from packer-owned extraction, validation, identity, and persistence.
## Context
Legacy source: `docs/studio/agendas/Palette Management in Studio Agenda.md`
Domain owner: `docs/studio`
Cross-domain impact: `docs/packer`
The retained agenda is intentionally scoped to `tile bank`.
The imported context keeps the same baseline:
- every `*.png` input of a tile bank is one tile;
- each tile yields one extracted palette during cache construction;
- developers may also work with favorite palettes and asset palettes;
- each bank may integrate at most `64` palettes;
- each palette contains `16` colors with a default color-key baseline;
- Studio owns curation UX, while packer remains authoritative for extraction, identity, validation, and persistence.
The current UI shape already converged on:
- a left-side transfer list for candidate and selected palettes;
- custom palette rendering with swatches and source indicators;
- a right-side preview panel with tile/file selector, tile preview, and applied palette strip.
## Open Questions
- [ ] How should Studio detect and present duplicate or near-equivalent palettes across tile-derived, favorite, and asset-level sources?
- [ ] Are favorites project-scoped references to existing palettes, or can they diverge into editable copies before bank admission?
- [ ] 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?
- [ ] Should extracted tile palettes always enter the candidate set automatically, or can the developer suppress some of them before curation?
- [ ] Should clicking a palette on the `selected` side be the only interaction needed to change the previewed palette in the first wave?
- [ ] Which palette operations are read-only in the first wave, and which require staged preview/apply treatment?
- [ ] Which parts of this interaction model should remain explicitly `tile bank`-specific, and which parts are reusable Studio form-session primitives?
- [ ] Does the first release need only an asset-scoped `tile bank` section, or also a project-level palette browser for discovery and favorites management?
## Options
### Option A - Automatic Integration
- **Approach:** Treat extracted tile palettes as implicit inputs and integrate them automatically without explicit user curation.
- **Pro:** Lowest immediate UX cost.
- **Con:** Hides palette-budget reasoning, weakens deliberate composition, and makes source distinctions harder to understand.
- **Maintainability:** Weak. It pushes important bank rules into implicit behavior.
### Option B - Asset-Scoped Curated Selection
- **Approach:** Treat bank palettes as an asset-scoped curated selection built from tile-derived palettes, favorites, and asset palettes, with Studio owning the curation UX and packer owning persistence.
- **Pro:** Matches the concrete `tile bank` workflow and keeps authority boundaries clear.
- **Con:** Requires explicit UX for capacity, identity, deduplication, and preview semantics.
- **Maintainability:** Strong. It makes responsibilities explicit and keeps family-specific rules close to the workflow that needs them.
### Option C - Studio-Owned Palette Library
- **Approach:** Treat palettes as a broader Studio-owned library/workspace with direct local editing and persistence behavior.
- **Pro:** Potentially flexible for future palette-heavy features.
- **Con:** Duplicates packer ownership and risks creating a second authority for bank composition.
- **Maintainability:** Weak. It expands Studio responsibility before the persistence contract is closed.
## Discussion
The imported agenda keeps the original recommendation intact: palette management should be first-class for `tile bank`, but Studio must not become the persistence authority.
That means the key open problem is not whether palettes exist. It is how Studio explains and curates them safely:
- candidate aggregation from multiple sources;
- clear source and identity display;
- explicit `1..64` capacity feedback;
- a preview model that stays tied to the selected bank palettes;
- a boundary between `tile bank`-specific UX and reusable Studio primitives.
The retained source already converged on a pragmatic first wave:
- transfer-list selection on the left;
- palette-focused preview on the right;
- first selected palette as default preview;
- clicking on a selected palette changes the previewed palette;
- removing the current preview palette falls back to the first remaining selected palette.
## Resolution
Recommended direction: adopt **Option B**.
The imported agenda preserves the retained Studio direction:
1. palette management belongs to the `tile bank` asset workflow;
2. Studio aggregates candidate palettes from tile-derived extraction, favorites, and asset palettes;
3. the first wave uses a custom-rendered transfer list with an explicit `1..64` selected range;
4. the right-side preview panel stays tied to the current selected palette set;
5. packer remains authoritative for extraction, identity, validation, and persistence;
6. broader standalone palette-authoring workflows remain deferred.
Next step suggestion: convert this imported agenda into a decision that closes the ownership boundary, candidate-source model, first-wave transfer-list UX, preview behavior, and reusable-vs-family-specific primitive boundary.
@@ -0,0 +1,97 @@
---
id: AGD-0004
ticket: tilemap-and-metatile-runtime-binary-layout
title: Tilemap and Metatile Runtime Binary Layout
status: open
created: 2026-03-26
resolved:
decision:
tags:
- packer
- legacy-import
- tilemap
- metatile
- runtime-layout
---
## Pain
The repository has conceptual alignment around map responsibility split and active-window residency, but still lacks a closed runtime binary contract for handheld maps.
Without a canonical decision:
- packer cannot close the output specification for map artifacts;
- runtime lacks one stable reading baseline;
- Studio cannot align authoring and preview schemas with one binary target.
## Context
Legacy source: `docs/packer/agendas/Tilemap and Metatile Runtime Binary Layout Agenda.md`
Domain owner: `docs/packer`
Cross-domain impact:
- `docs/vm-arch`
- `docs/studio`
- `docs/compiler/pbs`
Current discussion premises retained from source:
- visual and collision concerns should remain separated;
- map cells should not duplicate large metadata per tile;
- only a `3x3` active window of maps should remain resident in memory;
- a `64 KiB` target budget per map bank has been discussed;
- `map bank` and `tileset bank` do not need identical size rules.
## Open Questions
- [ ] Is `collisionId` with `5` bits (`32` classes) sufficient for expected projects?
- [ ] Should `flag0` be reserved for fast trigger semantics or contextual visual variation?
- [ ] Which optional chunks belong in `V1`, and which should wait for a later version?
- [ ] Must `map bank` stay strictly at `64 KiB`, or should capacity be variable with explicit metadata?
- [ ] What compression policy should the packer adopt by default for the stream?
## Options
### Option A - `u8` cells with auxiliary tables
- **Approach:** Store only one `metatileId` per cell and derive collision/flags from side tables.
- **Pro:** Smallest RAM and I/O footprint.
- **Con:** Pushes too much semantic meaning into external lookup tables.
- **Maintainability:** Medium.
### Option B - `u16` bit-packed cells
- **Approach:** Use `16` bits per cell, with a compact split such as `visualId`, `collisionId`, and `flag0`.
- **Pro:** Balances compactness, deterministic decoding, and enough expressivity for many handheld cases.
- **Con:** Leaves less room for inline per-cell growth than `u32`.
- **Maintainability:** Strong.
### Option C - `u32` cells
- **Approach:** Use larger cells to keep more event/flag space inline.
- **Pro:** Highest flexibility for per-cell triggers and future expansion.
- **Con:** Doubles memory cost versus `u16` without current evidence that it is needed.
- **Maintainability:** Weak for the current budget target.
## Discussion
The retained source already converged toward `u16` as the best baseline.
The suggested runtime shape is:
- fixed map header;
- contiguous cell stream;
- optional future-proof chunks.
The proposed `U16_PACKED_V1` split keeps visual and collision references compact while preserving predictable memory usage and straightforward streaming behavior for a handheld target.
## Resolution
Recommended direction: adopt **Option B** as the baseline.
Imported retained recommendation:
1. authorship stays JSON-oriented around compact ids;
2. build output packs deterministically into `U16_PACKED_V1`;
3. runtime active-window budget remains explicit;
4. any move to `u32` should happen only through a later versioned encoding with evidence of need.
Next step suggestion: convert this agenda into a decision that closes `U16_PACKED_V1`, propagation to `docs/vm-arch`, Studio editing schema alignment, and implementation planning for roundtrip tests.
@@ -0,0 +1,87 @@
---
id: AGD-0005
ticket: variable-tile-bank-palette-serialization
title: Variable Tile Bank Palette Serialization
status: open
created: 2026-03-26
resolved:
decision:
tags:
- packer
- legacy-import
- tile-bank
- palette-serialization
- versioning
---
## Pain
The current tile-bank contract serializes a fixed block of `64` palettes in v1 even when an asset authors far fewer palettes.
That keeps decoding simple, but it wastes cartridge space and leaves the system with a deliberate mismatch between authored and serialized palette counts.
## Context
Legacy source: `docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md`
Domain owner: `docs/packer`
Cross-domain dependency:
- runtime
Current aligned v1 contract:
- pixels are serialized as packed `u4`;
- palettes are serialized as `RGB565 u16`;
- `palette_count = 64`;
- payload size includes a fixed `64 * 16 * 2` palette block.
The packer now exposes:
- `metadata.palette_count = 64`
- `metadata.palette_authored = <actual authored count>`
## Open Questions
- [ ] Should variable palette serialization arrive as a new payload version or as an incompatible change to the current one?
- [ ] If `palette_count` becomes variable, should runtime still materialize a 64-slot resident bank, or truly shrink in-memory representation too?
- [ ] Should sparse authored palette indices remain sparse in serialization, or be canonicalized into a dense runtime block?
- [ ] Which domain owns compatibility for existing cartridges: `packer`, `runtime`, or `shipper`?
## Options
### Option A - Keep fixed 64-palette serialization
- **Approach:** Preserve the current fixed v1 payload with zero-filled unused palette slots.
- **Pro:** No runtime change and current specs/tests remain stable.
- **Con:** Every tile bank keeps paying the full palette cost.
- **Maintainability:** Medium.
### Option B - Move to variable palette serialization now
- **Approach:** Serialize only authored palettes and shrink payload size immediately.
- **Pro:** Better cartridge efficiency and tighter semantics for `palette_count`.
- **Con:** Reopens a just-stabilized cross-domain runtime contract and forces compatibility decisions now.
- **Maintainability:** Medium if done carefully, risky if done incidentally.
### Option C - Keep v1 fixed and design variable serialization for v2
- **Approach:** Preserve v1 stability now and open a later versioned follow-up for variable palette serialization.
- **Pro:** Keeps current work stable while preserving a clean path for future optimization.
- **Con:** Known waste remains in v1.
- **Maintainability:** Strong.
## Discussion
The retained agenda recommendation is already clear: the waste is real, but it is not a correctness bug, and reopening the runtime-facing contract immediately would mix optimization work into a freshly stabilized path.
That makes versioned follow-up a cleaner vehicle than incidental mutation of the current contract.
## Resolution
Recommended direction: adopt **Option C**.
Imported retained recommendation:
1. keep the current fixed 64-palette contract for v1;
2. if variable serialization is desired, design it explicitly as a versioned follow-up;
3. treat compatibility, runtime representation, and sparse-vs-dense palette identity as explicit next-wave questions rather than silent payload tweaks.
Next step suggestion: if the team wants to remove the fixed padding, open the corresponding runtime-side discussion and close the versioning/compatibility story before planning implementation.