tiled parser discussion

discussion/index.ndjson

@@ -1,5 +1,5 @@
-{"type":"meta","next_id":{"DSC":29,"AGD":31,"DEC":27,"PLN":53,"LSN":40,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":29,"AGD":31,"DEC":28,"PLN":56,"LSN":40,"CLSN":1}}
-{"type":"discussion","id":"DSC-0028","status":"open","ticket":"studio-tiled-parser-assets-scene-asset-type","title":"Tiled Parser and Scene Asset-Type Ownership in Assets Workspace","created_at":"2026-04-15","updated_at":"2026-04-15","tags":["studio","assets","scene","tiled","parser","asset-type"],"agendas":[{"id":"AGD-0030","file":"AGD-0030-tiled-parser-and-scene-asset-type.md","status":"open","created_at":"2026-04-15","updated_at":"2026-04-15"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0028","status":"open","ticket":"studio-tiled-parser-assets-scene-asset-type","title":"Tiled Parser and Scene Asset-Type Ownership in Assets Workspace","created_at":"2026-04-15","updated_at":"2026-04-17","tags":["studio","assets","scene","tiled","parser","asset-type"],"agendas":[{"id":"AGD-0030","file":"AGD-0030-tiled-parser-and-scene-asset-type.md","status":"accepted","created_at":"2026-04-15","updated_at":"2026-04-17"}],"decisions":[{"id":"DEC-0027","file":"DEC-0027-tiled-parser-and-scene-bank-asset-ownership.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_agenda":"AGD-0030"}],"plans":[{"id":"PLN-0053","file":"PLN-0053-scene-bank-asset-contract-and-studio-metadata-foundations.md","status":"open","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0027"]},{"id":"PLN-0054","file":"PLN-0054-tiled-xml-io-and-scene-bank-file-orchestration.md","status":"open","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0027"]},{"id":"PLN-0055","file":"PLN-0055-assets-workspace-scene-bank-validation-and-acceptance-flow.md","status":"open","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0027"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0027","status":"abandoned","ticket":"studio-scene-workspace","title":"Scene Workspace for SCENE Authoring","created_at":"2026-04-14","updated_at":"2026-04-15","tags":["studio","workspace","scene","tilemap","asset","runtime-alignment"],"agendas":[{"id":"AGD-0029","file":"AGD-0029-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted agenda and its downstream work."}],"decisions":[{"id":"DEC-0026","file":"DEC-0026-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_agenda":"AGD-0029","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted decision and stop using it as normative guidance."}],"plans":[{"id":"PLN-0049","file":"PLN-0049-scene-workspace-spec-and-boundary-propagation.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0050","file":"PLN-0050-scene-workspace-shell-and-project-state-foundations.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0051","file":"PLN-0051-scene-artifact-and-assets-handoff-contract.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0052","file":"PLN-0052-scene-workspace-wave-1-tilemap-editor.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."}],"lessons":[]}
 {"type":"discussion","id":"DSC-0026","status":"done","ticket":"glyph-bank-naming-alignment-with-runtime","title":"Glyph Bank Naming Alignment with Runtime DEC-0006","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["packer","studio","naming","asset-contract","runtime-alignment","glyph-bank"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0026-glyph-bank-naming-alignment-with-runtime/LSN-0040-glyph-bank-artifact-naming-alignment.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
 {"type":"discussion","id":"DSC-0025","status":"done","ticket":"packer-pipeline-metadata-ownership","title":"Pipeline Metadata Ownership and Runtime Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["packer","metadata","runtime-contract","tooling","studio"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"discussion/lessons/DSC-0025-packer-pipeline-metadata-ownership/LSN-0039-runtime-header-boundary-and-tooling-owned-pipeline-metadata.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}

discussion/workflow/agendas/AGD-0030-tiled-parser-and-scene-asset-type.md

@@ -2,10 +2,10 @@
 id: AGD-0030
 ticket: studio-tiled-parser-assets-scene-asset-type
 title: Tiled Parser and Scene Asset-Type Ownership in Assets Workspace
-status: open
+status: accepted
 created: 2026-04-15
-resolved:
+resolved: 2026-04-17
-decision:
+decision: DEC-0027
 tags:
   - studio
   - assets
@@ -125,7 +125,10 @@ There is already one strong constraint from the user:
 
 The current direction also suggests an important simplification:
 
-- Prometeu can assume one tileset per tilemap in its first wave;
+- Prometeu can assume exactly one tileset per tilemap in its first wave;
+- a `Scene Bank` may contain more than one tilemap asset in the same bank scope;
+- each scene may contain up to `4` layers in wave 1;
+- each scene layer is associated with one tilemap, so a scene bank may keep more than one `TMX` file in the same asset directory;
 - the parser still needs to understand `Tiled` identifiers correctly, but the Studio-side scene model can intentionally narrow to one linked `Tileset` glyph bank per map;
 - this keeps the runtime/editor model simpler while still using `Tiled` as the interchange and tooling format.
 
@@ -164,15 +167,23 @@ Implications:
 
 #### 1. Persistence model of the new `Scene Bank`
 
-Direction: the new `Scene Bank` MUST persist its own Studio-owned asset format.
+Direction: the new `Scene Bank` MUST persist full `TMX` documents as its maintained Studio asset format, plus any additional support files needed by the asset.
 
 Implications:
 
-- the `Scene Bank` is not a raw persisted `TMX` document;
+- the `Scene Bank` keeps `TMX` as the authoritative map-side document format rather than normalizing into a separate Studio-owned scene schema;
-- the Studio-owned format MUST retain the identity relationships and internal references needed to regenerate `TMX` deterministically;
+- one scene-facing asset directory may contain more than one `TMX` file, because a scene may bind distinct tilemaps to distinct layers;
-- the Studio may generate and keep the corresponding `TMX` as a derived Tiled-facing artifact for the asset;
+- wave 1 limits each scene to at most `4` layers;
+- the asset may include additional Studio support files alongside the maintained `TMX`;
+- those support files own the Studio-side convention that maps scene layers to the corresponding tilemaps;
+- the `Assets` workspace may expose a dedicated area to inspect and edit that scene-bank support data;
+- `TMX` generation remains part of the Studio asset flow, but the generated `TMX` is also the canonical maintained map document for the asset bank;
 - final pack materialization into a dedicated `assets.pa` representation is explicitly outside this wave.
 
+Implementation note accepted during agenda convergence:
+
+- the exact shape of the support files is intentionally deferred and may be discovered during implementation, as long as the final direction preserves an explicit layer-to-tilemap mapping owned by the scene-facing asset.
+
 #### 2. Ownership of scene-asset management in `Assets`
 
 Direction: the `Assets` workspace MUST fully manage the scene-facing asset lifecycle.
@@ -193,15 +204,30 @@ Implications:
 - the Studio must be able to ingest existing `TMX` and `TSX` documents;
 - the Studio must also emit `TMX` and `TSX` documents from its owned asset state.
 
+#### 3a. Asset-file placement and reference model
+
+Direction: `TSX` files are generated by the `Glyph Bank` asset specialized as `Tileset`, and `TMX` files are generated inside the scene-facing asset and must reference those generated `TSX` files in the tileset asset directories.
+
+Implications:
+
+- a `Tileset` specialization on a `Glyph Bank` owns the generation of the Tiled-facing `TSX` files for that asset;
+- the scene-facing asset owns the generation and maintenance of the corresponding `TMX` files;
+- each tilemap inside the scene-facing asset must reference exactly one generated `TSX` in wave 1;
+- the reference path model between `TMX` and `TSX` must remain deterministic so the asset bank can be regenerated and validated safely.
+
+Open precision still to be normalized in the future:
+
+- the exact canonical naming convention for multiple `TMX` files in the same scene-bank directory is not yet fixed, but it must be canonical and must remain compatible with the layer-to-tilemap support-file convention.
+
 #### 4. Pack boundary for the current wave
 
 Direction: pack integration is NOT part of the current wave.
 
 Implications:
 
-- the current work should stay inside Studio until the asset model and Tiled interop are normalized;
+- the current work should stay inside Studio until the asset model and Tiled interop are stabilized;
 - no packer-facing publication or final asset-pack contract is required to move this agenda forward;
-- later pack work can materialize a dedicated `assets.pa` representation once the Studio-side model has stabilized.
+- later pack work will materialize the `TMX`/`TSX` asset mass plus support files into a dedicated binary representation.
 
 #### 5. Persistence of the Studio-only specialization flag
 
@@ -235,6 +261,16 @@ Implications:
 - the same diagnostic discipline should block pack when inconsistencies remain;
 - this keeps the failure model aligned with the existing asset-validation experience rather than introducing a second error system.
 
+#### 7a. External-edit acceptance workflow
+
+Direction: wave 1 MUST use an explicit acceptance workflow between Studio-owned scene assets and external `Tiled` edits.
+
+Implications:
+
+- the initial workflow is: create the scene asset in Studio, edit the generated `TMX`/`TSX` documents in `Tiled`, then return to Studio to validate and explicitly accept the resulting changes;
+- a scene bank is considered ready only after Studio validation succeeds and the user explicitly accepts the converged state;
+- Studio remains the place where external edits are reviewed and accepted, rather than auto-merging them silently.
+
 #### 8. Supported Tiled feature subset in wave 1
 
 Direction: wave 1 should support `Object Layers`, properties, flips, and collisions from the start.
@@ -279,14 +315,15 @@ Accepted local direction for this agenda:
 - visibility and enablement of those commands SHOULD be driven by the Studio-only specialization flag of the glyph bank;
 - the summary remains responsible for identity and type presentation, including the complementary specialization chip.
 
-That makes Option A the current best fit for convergence, but it still needs the agenda to narrow the supported `Tiled` subset, the one-tileset-per-map constraint, and the editorial-role contract before a new decision can be written.
+That makes Option A the current best fit for convergence, and the latest discussion now also closes the first-wave one-tileset-per-tilemap rule, `TMX`/`TSX` asset ownership, and the explicit Studio-side acceptance workflow for external `Tiled` edits. The remaining work is to turn those accepted directions into a precise decision text while marking the support-file shape and multi-`TMX` naming convention as intentionally deferred implementation details.
 
 ## Resolution
 
 Recommended next step:
 
-- converge this agenda around a first-wave `Tiled` subset;
+- write a replacement decision for `Scene Bank` ownership in `Assets`;
-- define whether the new scene asset is raw-imported or normalized;
+- codify `TMX` as the maintained map document format and `TSX` as the tileset-facing generated format;
-- lock the Studio-only glyph-bank specialization-flag model for `Tileset`, `Sprites`, and `UI`;
+- codify the first-wave rule of exactly one tileset per tilemap, while allowing more than one tilemap inside a `Scene Bank`;
-- lock the first-wave one-tileset-per-map rule;
+- codify the Studio-only glyph-bank specialization-flag model for `Tileset`, `Sprites`, and `UI`;
-- then write a replacement decision for asset ownership, parser boundary, and wave-1 scope.
+- codify the wave-1 supported `Tiled` subset, validation model, and explicit acceptance flow for external edits;
+- carry forward the support-file shape and multi-`TMX` naming convention as deferred implementation details rather than pretending they are already closed.

discussion/workflow/decisions/DEC-0027-tiled-parser-and-scene-bank-asset-ownership.md

@@ -0,0 +1,139 @@
+---
+id: DEC-0027
+ticket: studio-tiled-parser-assets-scene-asset-type
+title: Tiled Parser and Scene Bank Asset Ownership in Assets Workspace
+status: accepted
+created: 2026-04-17
+accepted: 2026-04-17
+agenda: AGD-0030
+plans: []
+tags:
+  - studio
+  - assets
+  - scene
+  - tiled
+  - parser
+  - asset-type
+---
+
+## Context
+
+The previous `Scene Workspace` direction was explicitly abandoned and MUST NOT be reused as the basis for new planning or implementation.
+
+The replacement direction is asset-first:
+
+- scene-facing ownership belongs to the `Assets` workspace;
+- `Tiled` is the external authoring and interchange surface for wave 1;
+- `Glyph Bank` remains the base runtime asset family for bank assets;
+- Studio-specific roles such as `Tileset`, `Sprites`, and `UI` are editorial specializations only and MUST NOT create new runtime asset families.
+
+This decision closes the ownership, persistence, interoperability, and validation baseline needed to plan and implement the first wave.
+
+## Decision
+
+The Studio SHALL adopt an asset-first `Scene Bank` model managed from the `Assets` workspace.
+
+Wave 1 SHALL use `TMX` and `TSX` as the Tiled-facing asset formats:
+
+- a `Scene Bank` MUST maintain full `TMX` documents as its canonical map-side asset documents;
+- a `Glyph Bank` specialized as `Tileset` MUST generate the `TSX` files used by scene tilemaps;
+- each tilemap MUST reference exactly one generated `TSX` file in wave 1;
+- a `Scene Bank` MAY contain more than one tilemap and therefore more than one `TMX` file in the same asset directory;
+- each scene MAY contain up to `4` layers in wave 1;
+- each scene layer MUST map to exactly one tilemap;
+- the layer-to-tilemap convention MUST be owned by Studio support files that live with the scene-facing asset.
+
+The Studio SHALL own creation, metadata, validation, consistency checks, and asset-facing operations for `Scene Bank` assets.
+
+Heavy map editing for wave 1 SHALL occur in `Tiled`, not in a dedicated Studio scene editor workspace.
+
+## Rationale
+
+This direction preserves the explicit user request to replace the discarded scene-workspace model with:
+
+- a parser for `Tiled`;
+- a new scene-facing asset managed from `Assets`;
+- Studio-only specialization over existing `Glyph Bank` assets instead of runtime-family multiplication.
+
+Keeping `TMX` as the maintained scene document avoids inventing a parallel normalized scene schema before the Tiled integration boundary is proven in practice.
+
+Keeping `TSX` generation attached to `Tileset`-specialized glyph banks preserves a clear ownership split:
+
+- tileset-facing generation belongs to the specialized glyph-bank asset;
+- scene-facing tilemap maintenance belongs to the scene asset;
+- runtime publication remains deferred until the Studio-side asset model stabilizes.
+
+The explicit acceptance workflow also prevents silent drift between Studio-owned asset state and externally edited Tiled documents.
+
+## Technical Specification
+
+### 1. Asset ownership and specialization
+
+- The `Assets` workspace MUST remain the management surface for `Scene Bank` assets.
+- `Glyph Bank` MUST remain the base asset type shown in summaries.
+- The Studio-only specialization flag MUST be stored on Studio-controlled asset metadata.
+- The specialization flag MUST be represented as an internal enum or equivalent closed set.
+- The specialization flag MUST NOT redefine the runtime asset family.
+- Specialization-specific actions MUST appear in the existing asset actions surface.
+- The summary SHOULD present the base type plus specialization chip, for example `Glyph Bank / Tileset`.
+
+### 2. Scene Bank persistence
+
+- A scene-facing asset directory MAY contain multiple `TMX` files.
+- The maintained scene-bank format MUST keep `TMX` in full rather than translating the asset into a separate normalized Studio scene format.
+- The asset MAY contain additional support files owned by Studio.
+- Those support files MUST encode the mapping between scene layers and tilemaps.
+- The exact support-file schema is intentionally deferred to implementation and MAY be discovered on the fly, but the resulting contract MUST remain explicit and deterministic.
+
+### 3. Tiled surfaces and parser contract
+
+- Wave 1 MUST support XML read/write for both `TMX` and `TSX`.
+- JSON export MUST NOT be treated as the primary interoperability surface in wave 1.
+- Studio MUST be able to ingest supported `TMX` and `TSX` documents.
+- Studio MUST be able to emit supported `TMX` and `TSX` documents from its owned asset state.
+
+### 4. Tilemap, tileset, and layer rules
+
+- Each tilemap MUST reference exactly one `Tileset` glyph-bank generated `TSX`.
+- One scene MAY contain multiple tilemaps.
+- Each scene MAY contain at most `4` layers in wave 1.
+- Each layer MUST point to one tilemap through the scene-bank support files.
+- The naming convention for multiple `TMX` files in one scene-bank directory is deferred, but the final convention MUST be canonical and MUST remain compatible with the layer-to-tilemap mapping.
+
+### 5. Supported Tiled subset in wave 1
+
+- Wave 1 MUST support `Object Layers`, properties, flips, and collisions.
+- Tile-owned collision MAY be represented on the `TSX` side of a `Tileset` glyph bank.
+- Map-owned collision MUST be represented through `Object Layer` content on the `TMX` side of the `Scene Bank`.
+- Infinite maps, templates, Wang sets, and animations are outside wave 1 unless revised by a later decision.
+
+### 6. Validation and acceptance workflow
+
+- The initial workflow SHALL be:
+  1. create the scene-facing asset in Studio;
+  2. edit the generated `TMX` and `TSX` documents in `Tiled`;
+  3. return to Studio;
+  4. validate the resulting state;
+  5. explicitly accept the converged changes.
+- Studio MUST surface invalid, unsupported, or broken references as diagnostics using the same general diagnostic discipline already used for glyph assets.
+- Studio MUST NOT silently auto-accept external `Tiled` edits.
+- A `Scene Bank` is ready only after Studio validation succeeds and the user explicitly accepts the resulting state.
+- The same diagnostic discipline SHOULD block later pack publication when inconsistencies remain.
+
+### 7. Pack boundary
+
+- Pack integration is explicitly outside this wave.
+- Wave-1 work MUST stay inside Studio asset management and Tiled interoperability.
+- Later pack work MAY materialize the `TMX`/`TSX` asset mass plus support files into a dedicated binary representation.
+
+## Constraints
+
+- This decision supersedes the abandoned `Scene Workspace` direction and MUST be treated as the normative replacement for wave-1 planning.
+- Plans derived from this decision MUST NOT reintroduce a dedicated scene workspace or a separate normalized Studio-owned scene format unless the user explicitly requests a revised decision.
+- Plans derived from this decision MUST preserve the external-edit acceptance step as a required gate.
+- Plans derived from this decision MUST treat the support-file schema and multi-`TMX` naming convention as deferred implementation details, not as permission to weaken the layer-to-tilemap contract.
+- Any future move toward automatic convergence, multi-tileset tilemaps, or pack-facing publication contracts requires a new decision or explicit revision of this one.
+
+## Revision Log
+
+- 2026-04-17: Initial accepted decision from AGD-0030.

discussion/workflow/plans/PLN-0053-scene-bank-asset-contract-and-studio-metadata-foundations.md

@@ -0,0 +1,121 @@
+---
+id: PLN-0053
+ticket: studio-tiled-parser-assets-scene-asset-type
+title: Scene Bank Asset Contract and Studio Metadata Foundations
+status: open
+created: 2026-04-17
+completed:
+tags:
+  - studio
+  - assets
+  - scene
+  - tiled
+  - metadata
+---
+
+## Objective
+
+Establish the asset contract and Studio-owned metadata foundations required by `DEC-0027` so `Scene Bank` assets and specialized `Glyph Bank` assets can exist in the `Assets` workspace without reintroducing a dedicated scene workspace or a separate normalized scene schema.
+
+## Background
+
+`DEC-0027` locks the following requirements that must be reflected in the asset contract before parser and UX work can be implemented safely:
+
+- `Scene Bank` is an asset owned by the `Assets` workspace.
+- `Glyph Bank` remains the base runtime asset family, with Studio-only specialization flags such as `Tileset`, `Sprites`, and `UI`.
+- `TMX` remains the maintained scene document format.
+- `Scene Bank` support files own the explicit `layer -> tilemap` mapping.
+- one scene may contain multiple tilemaps, with up to `4` layers in wave 1.
+
+The current repo already has the asset creation and detail surfaces under `prometeu-studio/src/main/java/p/studio/workspaces/assets` and the asset manifest/runtime contract under `prometeu-packer/prometeu-packer-v1`.
+
+## Scope
+
+### Included
+- Add `Scene Bank` as a first-class asset option in the Studio asset creation and details pipeline.
+- Add the Studio-only specialization model for `Glyph Bank` assets, including `Tileset`, `Sprites`, and `UI`.
+- Define where Studio-owned scene support files and specialization metadata live relative to existing asset roots.
+- Add summary/details projection support so the `Assets` workspace can display base family plus specialization chip.
+- Define the wave-1 metadata contract for scene-layer mapping and scene-bank limits.
+
+### Excluded
+- TMX/TSX XML parsing and serialization logic.
+- External-edit acceptance UI or file-diff validation flows.
+- Pack publication of scene assets into runtime binary formats.
+
+## Execution Steps
+
+### Step 1 - Extend asset family and metadata models
+
+**What:** Introduce the data models needed for `Scene Bank` assets and Studio-only glyph-bank specialization.
+
+**How:** Update the packer/studio shared asset declarations and detail projection pipeline so `Scene Bank` can be created, read, and surfaced by the `Assets` workspace while keeping `Glyph Bank` as the underlying runtime family for specializations. Define the Studio-only specialization enum and the scene-bank support metadata surface that will later carry `layer -> tilemap` mapping and wave-1 constraints.
+
+**File(s):**
+- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
+- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java`
+- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetSummary.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java`
+- additional shared DTOs or catalogs discovered from the asset declaration flow
+
+### Step 2 - Add creation and details support in Assets workspace
+
+**What:** Make `Scene Bank` and glyph-bank specialization available in the actual Studio asset workflow.
+
+**How:** Extend the add-asset wizard to expose `Scene Bank` as an asset type and add the minimum specialization capture or follow-up action path for `Glyph Bank`. Update details/summary rendering to show `Glyph Bank / Tileset`-style presentation and to surface scene-bank metadata ownership in the details view without inventing a separate workspace region.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/AddAssetWizard.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/summary/AssetDetailsSummaryControl.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsUiSupport.java`
+- `prometeu-studio/src/main/resources/i18n/messages.properties`
+
+### Step 3 - Define on-disk scene-bank support-file baseline
+
+**What:** Establish the first implementation-owned support-file baseline for scene banks.
+
+**How:** Introduce a concrete but implementation-scoped support-file format that records scene layer count, `layer -> tilemap` mapping, and references needed by the `Assets` workspace. The plan MUST preserve the decision rule that the exact shape can be discovered during implementation, but the result MUST be explicit, deterministic, and colocated with the scene asset root.
+
+**File(s):**
+- asset-root support files under `test-projects/main/assets/...` fixtures
+- implementation targets discovered while wiring Studio asset persistence
+- related tests in `prometeu-studio/src/test/java/p/studio/workspaces/assets/...` and `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/...`
+
+## Test Requirements
+
+### Unit Tests
+
+- Add parser/service tests proving `Scene Bank` assets can be created and read through the asset declaration pipeline.
+- Add Studio projection tests proving summary/details surfaces can represent base family plus specialization.
+- Add tests for the support-file metadata model, including `1..4` layer constraints and explicit `layer -> tilemap` mapping requirements.
+
+### Integration Tests
+
+- Extend asset workspace service tests to verify end-to-end creation of a `Scene Bank` asset root and detail retrieval.
+- Add or update test fixtures under `test-projects/main/assets` to cover specialized glyph banks and scene-bank roots with multiple tilemaps.
+
+### Manual Verification
+
+- Create a new `Scene Bank` from the Assets workspace and confirm the asset appears in the list/details flow.
+- Create or mark a `Glyph Bank` as `Tileset` and confirm the summary shows base family plus specialization chip.
+
+## Acceptance Criteria
+
+- [ ] `Scene Bank` exists as a first-class asset choice in the Studio asset flow.
+- [ ] Studio-only glyph-bank specialization is represented by a closed metadata set and does not redefine the runtime asset family.
+- [ ] The Assets workspace can display base family and specialization together in the summary/details flow.
+- [ ] Scene-bank support metadata explicitly records `layer -> tilemap` mapping and enforces the wave-1 `4`-layer limit.
+- [ ] No plan step introduces a dedicated scene workspace or a normalized Studio-owned scene format.
+
+## Dependencies
+
+- Depends on `DEC-0027`.
+- Unblocks `PLN-0054` and `PLN-0055`.
+
+## Risks
+
+- The current asset declaration pipeline may assume existing family/output combinations too rigidly, which can force deeper changes in packer services than the UI suggests.
+- If specialization metadata is embedded in the wrong layer, Studio-only editorial flags may leak into runtime-facing contracts.
+- If the support-file baseline is too vague, later parser and validation work will drift on naming and ownership.

discussion/workflow/plans/PLN-0054-tiled-xml-io-and-scene-bank-file-orchestration.md

@@ -0,0 +1,120 @@
+---
+id: PLN-0054
+ticket: studio-tiled-parser-assets-scene-asset-type
+title: Tiled XML IO and Scene Bank File Orchestration
+status: open
+created: 2026-04-17
+completed:
+tags:
+  - studio
+  - assets
+  - scene
+  - tiled
+  - parser
+---
+
+## Objective
+
+Implement the wave-1 XML read/write pipeline for `TMX` and `TSX`, including deterministic file placement and reference orchestration between `Scene Bank` tilemaps and `Tileset`-specialized glyph-bank assets.
+
+## Background
+
+`DEC-0027` requires wave-1 XML read/write support for both `TMX` and `TSX`, keeps `TMX` as the maintained scene document, and requires each tilemap to reference exactly one generated `TSX`. It also keeps naming details implementation-owned, but requires the resulting convention to be canonical and compatible with explicit `layer -> tilemap` mapping.
+
+The repository already contains example `TMX` and `TSX` files under `test-projects/main/assets/scenes` and `test-projects/main/assets/Zelda3`, which can be promoted into fixture coverage.
+
+## Scope
+
+### Included
+- Add XML read/write support for supported `TMX` and `TSX` surfaces.
+- Generate `TSX` from `Tileset`-specialized glyph-bank assets.
+- Generate and maintain one or more `TMX` files inside a `Scene Bank` asset root.
+- Define and implement a canonical naming/reference convention for multiple `TMX` files compatible with scene support metadata.
+- Preserve supported wave-1 Tiled features: object layers, properties, flips, and collisions.
+
+### Excluded
+- Studio UX for validating and accepting external edits.
+- Pack/runtime materialization of scene data.
+- Support for infinite maps, templates, Wang sets, or animations.
+
+## Execution Steps
+
+### Step 1 - Introduce Tiled XML domain models and codecs
+
+**What:** Create the XML-side models and serialization services for supported `TMX` and `TSX`.
+
+**How:** Add parser/writer services that cover the accepted wave-1 subset, preserving round-trip stability for supported fields and producing explicit diagnostics for unsupported constructs. Keep the implementation aligned to XML as the primary interoperability surface and avoid JSON-export dependencies.
+
+**File(s):**
+- new `prometeu-studio/src/main/java/p/studio/.../tiled/...` package(s) discovered during implementation
+- related tests under `prometeu-studio/src/test/java/p/studio/.../tiled/...`
+
+### Step 2 - Generate TSX from Tileset-specialized glyph banks
+
+**What:** Add the generation path that emits `TSX` for `Glyph Bank` assets specialized as `Tileset`.
+
+**How:** Extend the asset action/details flow so a `Tileset` glyph bank can materialize its Tiled-facing `TSX` file in the asset root. The generated `TSX` MUST include the supported tileset-side collision/properties surface needed by wave 1 and MUST remain deterministic for later scene references.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetAction.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java`
+- implementation packages created for Tiled file generation
+
+### Step 3 - Generate and maintain TMX files inside Scene Bank assets
+
+**What:** Add the file orchestration path for one scene with up to `4` layer-linked tilemaps.
+
+**How:** Use the scene-bank support metadata from `PLN-0053` to generate and maintain one or more canonical `TMX` files in the scene asset root. Each `TMX` MUST reference exactly one generated `TSX` from a `Tileset` glyph-bank asset, and the chosen naming convention MUST remain stable across regenerate/validate cycles.
+
+**File(s):**
+- scene-bank persistence/orchestration services added under `prometeu-studio/src/main/java/p/studio/...`
+- test fixtures under `test-projects/main/assets/scenes` and related asset roots
+
+### Step 4 - Enforce supported subset and failure behavior
+
+**What:** Formalize the wave-1 supported subset and rejection behavior for unsupported input.
+
+**How:** Add diagnostic-producing validation around XML ingest so unsupported Tiled constructs fail explicitly and do not silently normalize away unsupported content. Cover tile-owned collision in `TSX` and map-owned collision via `Object Layer` in `TMX`.
+
+**File(s):**
+- Tiled parser/validator packages introduced in this plan
+- diagnostics surfaces reused by the Assets workspace
+
+## Test Requirements
+
+### Unit Tests
+
+- Add TMX parser/writer round-trip tests for supported map metadata, layers, object layers, properties, flips, and collision cases.
+- Add TSX parser/writer round-trip tests for supported tileset metadata and tile-owned collision/properties.
+- Add tests for rejection/diagnostics on unsupported features such as infinite maps, templates, Wang sets, and animations.
+
+### Integration Tests
+
+- Add end-to-end fixture tests proving a `Tileset` glyph bank can generate `TSX` and a `Scene Bank` can generate one or more `TMX` files referencing it.
+- Add tests proving canonical `TMX` naming remains stable across regeneration using the same support metadata.
+
+### Manual Verification
+
+- Generate `TSX` from a `Tileset` glyph bank and open it in Tiled.
+- Generate a multi-tilemap scene-bank root and confirm each `TMX` opens in Tiled and points to the expected `TSX`.
+
+## Acceptance Criteria
+
+- [ ] Studio can read and write the supported XML subset for both `TMX` and `TSX`.
+- [ ] `Tileset`-specialized glyph banks can generate deterministic `TSX` files.
+- [ ] `Scene Bank` assets can maintain multiple canonical `TMX` files in one asset root.
+- [ ] Every generated tilemap references exactly one generated `TSX` in wave 1.
+- [ ] Unsupported Tiled features fail with explicit diagnostics instead of silent degradation.
+
+## Dependencies
+
+- Depends on `DEC-0027`.
+- Depends on `PLN-0053` for asset metadata and support-file ownership.
+- Unblocks `PLN-0055`.
+
+## Risks
+
+- XML round-trip fidelity can drift if parser and writer models are not designed from the same canonical structure.
+- Canonical naming and path resolution may become unstable if they are derived from mutable UI labels instead of explicit metadata.
+- TSX generation can accidentally encode Studio-only specialization state into runtime-facing data if the boundary is not kept strict.

discussion/workflow/plans/PLN-0055-assets-workspace-scene-bank-validation-and-acceptance-flow.md

@@ -0,0 +1,120 @@
+---
+id: PLN-0055
+ticket: studio-tiled-parser-assets-scene-asset-type
+title: Assets Workspace Scene Bank Validation and Acceptance Flow
+status: open
+created: 2026-04-17
+completed:
+tags:
+  - studio
+  - assets
+  - scene
+  - validation
+  - ux
+---
+
+## Objective
+
+Implement the `Assets` workspace flow that validates external `Tiled` edits, surfaces diagnostics, and requires explicit Studio-side acceptance before a `Scene Bank` is considered ready.
+
+## Background
+
+`DEC-0027` requires the initial workflow to be:
+
+1. create the scene asset in Studio;
+2. edit generated `TMX`/`TSX` in `Tiled`;
+3. return to Studio;
+4. validate;
+5. explicitly accept the converged changes.
+
+The decision explicitly forbids silent auto-acceptance and requires the same general diagnostic discipline already used for glyph assets. The current `Assets` workspace already contains refresh, detail, action, and diagnostics surfaces that can host this flow without creating a dedicated scene workspace.
+
+## Scope
+
+### Included
+- Add scene-bank validation state to the `Assets` workspace projections.
+- Add explicit actions to validate and accept external scene-bank changes.
+- Surface scene/Tiled diagnostics in the existing asset details/logging patterns.
+- Ensure readiness/build participation reflects acceptance state for scene banks.
+
+### Excluded
+- Automatic merge/convergence of external edits.
+- A dedicated scene-editing workspace.
+- Pack/runtime publication.
+
+## Execution Steps
+
+### Step 1 - Extend asset details state for scene-bank validation
+
+**What:** Add the projection/state needed to represent scene-bank validation and acceptance status in the assets UI.
+
+**How:** Extend the asset workspace message and detail-state models so scene-bank assets can expose pending external changes, validation result, acceptance readiness, and scene-specific actions while reusing the current details/action host rather than adding a separate workspace.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceDetailsViewState.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetAction.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/dialogs/AssetDiagnosticsDialog.java`
+
+### Step 2 - Add validate/accept actions to existing assets action surface
+
+**What:** Add the concrete user actions for scene-bank validation and explicit acceptance.
+
+**How:** Extend the existing asset actions surface so scene-bank assets can trigger validation against current `TMX`/`TSX` and then explicitly accept the converged result. Keep these actions stacked with existing asset actions, in line with `DEC-0027`, and ensure availability is driven by asset family/state rather than a new intermediate panel.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/summary/AssetDetailsSummaryControl.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsUiSupport.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...` action-host controls discovered during implementation
+- `prometeu-studio/src/main/resources/i18n/messages.properties`
+
+### Step 3 - Connect validation results to diagnostics and readiness gates
+
+**What:** Make validation outcome meaningful to the workflow.
+
+**How:** Reuse the current diagnostic/log/event patterns so unsupported references, broken paths, invalid tilemap-to-layer mapping, and unsupported Tiled constructs surface as diagnostics. Mark the scene bank as not ready until validation succeeds and explicit acceptance is recorded. Reflect this status in build participation or equivalent readiness signals without implementing pack publication itself.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/events/...`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetLogsPane.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
+- any validation coordinator/services created for scene-bank acceptance
+
+## Test Requirements
+
+### Unit Tests
+
+- Add tests for scene-bank details state transitions: created, externally changed, validation failed, validation passed, accepted.
+- Add tests proving accept is unavailable when validation diagnostics remain.
+- Add tests proving scene-bank actions are hosted in the existing asset actions surface.
+
+### Integration Tests
+
+- Add assets workspace tests covering refresh after external file edits, validation, diagnostics surfacing, and explicit acceptance.
+- Add fixture-backed tests covering invalid TSX references, unsupported TMX features, and broken layer-to-tilemap mappings.
+
+### Manual Verification
+
+- Create a scene bank in Studio, edit its `TMX`/`TSX` externally in Tiled, return to Studio, validate, and explicitly accept.
+- Confirm the asset stays unready when diagnostics remain and becomes ready only after successful validation plus explicit acceptance.
+
+## Acceptance Criteria
+
+- [ ] Scene-bank assets expose validate/accept actions in the existing asset action surface.
+- [ ] Studio surfaces scene-bank diagnostics using the existing general diagnostic discipline.
+- [ ] Studio does not silently auto-accept external `Tiled` edits.
+- [ ] A scene bank is not considered ready until validation succeeds and the user explicitly accepts the result.
+- [ ] No part of the workflow introduces a dedicated scene workspace.
+
+## Dependencies
+
+- Depends on `DEC-0027`.
+- Depends on `PLN-0053` for asset/state foundations.
+- Depends on `PLN-0054` for TMX/TSX ingest and validation inputs.
+
+## Risks
+
+- If refresh and validation state are coupled too loosely, the UI can show stale readiness after external edits.
+- If acceptance is represented only in transient UI state, Studio may lose the required gate after reload.
+- If diagnostics are not normalized with existing asset flows, scene-bank errors will feel like a separate subsystem.

test-projects/main/assets/scenes/primeiro mapa.tmx

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<map version="1.10" tiledversion="1.12.1" orientation="orthogonal" renderorder="right-down" width="25" height="25" tilewidth="16" tileheight="16" infinite="0" nextlayerid="6" nextobjectid="13">
+<map version="1.10" tiledversion="1.12.1" orientation="orthogonal" renderorder="right-down" width="25" height="25" tilewidth="16" tileheight="16" infinite="0" nextlayerid="6" nextobjectid="20">
  <tileset firstgid="1" source="../Zelda3/primeiro tileset.tsx"/>
  <layer id="1" name="Tile Layer 1" width="25" height="25">
   <data encoding="csv">
@@ -35,5 +35,12 @@
   <object id="12" x="179.608" y="48.6275">
    <polygon points="0,0 1.17647,50.1961 46.2745,51.3725 44.7059,19.2157 12.9412,19.6078 12.549,-0.784314"/>
   </object>
+  <object id="13" x="116.078" y="26.2745" width="34.902" height="39.2157"/>
+  <object id="14" x="96" y="96" width="52.2353" height="45.9608"/>
+  <object id="15" x="160" y="112" width="32" height="32"/>
+  <object id="16" x="16" y="96" width="64" height="32"/>
+  <object id="17" x="96" y="0" width="80" height="64"/>
+  <object id="18" x="153.725" y="92.1569"/>
+  <object id="19" x="98.0392" y="-48.2353" height="23.5294"/>
  </objectgroup>
 </map>