initial studies over Tiled@

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

@@ -41,6 +41,7 @@ Cross-domain impact:
 - asset typing and creation flows in the `Assets` workspace;
 - Studio-side parsing/import rules for `Tiled`;
 - possible downstream alignment with runtime-facing `SCENE` publication, depending on the chosen import boundary.
+- Studio-only specialization of glyph-bank assets into map, sprite, and UI authoring roles.
 
 User direction explicitly provided on 2026-04-15:
 
@@ -49,24 +50,39 @@ User direction explicitly provided on 2026-04-15:
 - instead, write a parser for `Tiled`;
 - create a new asset type managed from the `Assets` workspace.
 
+Additional direction explicitly provided on 2026-04-15:
+
+- Studio-specific asset roles such as `Tileset`, `Sprites`, and `UI` remain glyph banks internally;
+- those roles are editorial specializations in Studio rather than distinct runtime asset families;
+- the specialization is stored as a Studio-only flag attached to glyph-bank asset creation and management;
+- specialization does not need to lock general glyph-bank editing fields in this wave;
+- specialization should instead enable role-specific Studio actions and flows;
+- the asset summary should continue to show the base bank type and add the specialization as a complementary chip, such as `Type: Glyph Bank / Tileset`;
+- Studio will expose role-specific commands, such as building a `tileset.tsx` from a `Tileset` glyph bank;
+- validation of map/tileset consistency should remain centered on the `Scene Bank` rather than on hard-locking the `Glyph Bank`.
+- specialization-specific actions should be stacked with the existing asset actions instead of introducing a separate action region between summary and actions.
+
 This agenda exists to turn that direction into a disciplined technical recommendation rather than jumping directly into implementation with undefined ownership and file-contract assumptions.
 
 ## Open Questions
 
-- [ ] Which `Tiled` surface is the primary input contract: TMX XML, JSON export, TSX, or a constrained subset of those?
-- [ ] Is the new asset type a raw imported `Tiled` document, a normalized Studio-owned intermediate asset, or a published runtime-facing `SCENE` derivative?
-- [ ] Should `Assets` own only creation/import and metadata management, or also the main editing/reimport flow for this new asset type?
-- [ ] How should tileset references inside `Tiled` map onto existing glyph-bank assets and asset identity rules in Studio?
-- [ ] What parts of `Tiled` are intentionally out of scope for the first wave: object layers, properties, flips, collisions, infinite maps, templates, Wang sets, animations?
-- [ ] Does the parser need to preserve full round-trip fidelity with `Tiled`, or only import the supported subset into Studio-owned structures?
-- [ ] What is the canonical failure model when a `Tiled` document references unsupported constructs or broken external assets?
+- [x] Which `Tiled` surface is the primary input contract: TMX XML, JSON export, TSX, or a constrained subset of those?
+- [x] Is the new scene-facing asset a raw imported `Tiled` document, a normalized Studio-owned intermediate asset, or a published runtime-facing `SCENE` derivative?
+- [x] Should `Assets` own only creation/import and metadata management, or also the main editing/reimport flow for `Tiled`-backed scene assets?
+- [x] How should `Tiled` tileset references map onto Studio-owned `Tileset` glyph banks and their identity rules?
+- [x] What parts of `Tiled` are intentionally out of scope for the first wave: object layers, properties, flips, collisions, infinite maps, templates, Wang sets, animations?
+- [x] Does the parser need to preserve full round-trip fidelity with `Tiled`, or only import the supported subset into Studio-owned structures?
+- [x] What is the canonical failure model when a `Tiled` document references unsupported constructs or broken external assets?
+- [x] How should Studio persist the editorial role flag of a glyph bank (`Tileset`, `Sprites`, `UI`) without inventing a separate runtime family?
+- [x] Which defaults become mandatory or locked for each Studio specialization at creation time?
+- [x] Where do Studio role-specific commands such as `build tileset.tsx` live in the `Assets` UX?
 
 ## Options
 
-### Option A - Import `Tiled` into a new Studio-owned scene asset type in `Assets`
-- **Approach:** Introduce a new asset type in `Assets`; parse supported `Tiled` files into a Studio-owned asset model managed from that workspace.
-- **Pro:** Aligns with the requested ownership shift, keeps authoring/import centered in `Assets`, and allows Studio to define a strict supported subset.
-- **Con:** Requires defining a clean normalized asset contract and a mapping layer from `Tiled` concepts to Studio/runtime concepts.
+### Option A - Import `Tiled` into a Studio-owned scene asset model linked to flagged glyph banks
+- **Approach:** Keep `Glyph Bank` as the canonical asset type, add a Studio-only specialization flag such as `Tileset`, `Sprites`, or `UI`, and parse supported `Tiled` files into a Studio-owned scene asset managed from `Assets`.
+- **Pro:** Aligns with the requested ownership shift, preserves the existing glyph-bank runtime model, and lets Studio attach role-specific rules, chips, defaults, and commands without multiplying runtime asset families.
+- **Con:** Requires a precise Studio metadata model for the specialization flag and a clear mapping from `Tiled` tilesets to flagged glyph-bank assets.
 - **Maintainability:** Strong, if the supported subset and ownership boundary are made explicit early.
 
 ### Option B - Treat `Tiled` files as external source documents and keep Studio as a thin importer/viewer
@@ -90,26 +106,187 @@ It is also a change in ownership:
 - scene-related authoring/import should no longer justify a dedicated `Scene Workspace`;
 - the `Assets` workspace becomes the management surface for the relevant asset type;
 - any parser choice must therefore fit an asset-first workflow instead of a separate editor-first workflow.
+- asset specialization such as `Tileset`, `Sprites`, and `UI` is a Studio concern layered over the existing glyph-bank runtime family.
 
 That creates several decisions that should be made deliberately:
 
 1. what exact `Tiled` contract Studio supports in wave 1;
 2. whether Studio stores `Tiled` data directly or through a normalized asset form;
-3. how glyph banks and tilesets map without creating identity ambiguity;
-4. how much of `Tiled` fidelity is preserved versus normalized away;
-5. whether editing is a reimport/update flow, a direct managed-asset flow, or some hybrid.
+3. how `Tileset` glyph banks map to `Tiled` tilesets without creating identity ambiguity;
+4. how Studio persists the specialization flag and summary-chip presentation without changing the runtime family model;
+5. which creation defaults become locked by each specialization;
+6. how much of `Tiled` fidelity is preserved versus normalized away;
+7. whether editing is a reimport/update flow, a direct managed-asset flow, or some hybrid.
 
 There is already one strong constraint from the user:
 
 - the previous `Scene Workspace` split should be considered discarded;
 - the new work should be organized around `Assets` plus a `Tiled` parser.
 
-That makes Option A the current best fit for convergence, but it still needs the agenda to narrow the supported `Tiled` subset and the resulting asset contract before a new decision can be written.
+The current direction also suggests an important simplification:
+
+- Prometeu can assume one tileset per tilemap in its first wave;
+- 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.
+
+Another important clarification is now explicit:
+
+- the `Assets` workspace remains the owner of asset management;
+- `Glyph Bank` remains the base type shown in the asset summary;
+- the Studio-only specialization appears as a complementary suffix or chip such as `Glyph Bank / Tileset`;
+- specialization-specific behavior such as locked dimensions or generated `TSX` output belongs strictly to Studio behavior rather than the runtime asset contract.
+- specialization-specific actions should reuse the existing actions surface rather than creating a new intermediate panel between summary and actions.
+
+### Convergence pass - accepted Tiled surfaces and tileset handoff
+
+#### 1. Supported Tiled surfaces for wave 1
+
+Direction: the Studio integration surface for wave 1 uses both `TMX` and `TSX`.
+
+Implications:
+
+- `TMX` is the map-side surface used for tilemap generation and interchange;
+- `TSX` is the tileset-side surface generated from a Studio `Glyph Bank` specialized as `Tileset`;
+- JSON export is not the primary interoperability surface for this wave.
+
+#### 2. Mapping from `Tileset` glyph banks to Tiled tilesets
+
+Direction: a `Glyph Bank` flagged as `Tileset` generates the `TSX` representation for that bank.
+
+Implications:
+
+- the generated `TSX` is the Tiled-facing tileset surface for that glyph bank;
+- the new `Scene Bank` may point to that generated `TSX` when generating a tilemap;
+- this coupling is scoped to tilemap generation and consumption, not to a runtime asset-family split;
+- `TSX` generation remains owned by the `Assets` workspace as Studio behavior over a `Glyph Bank`.
+
+### Convergence pass - accepted Scene Bank and parser direction
+
+#### 1. Persistence model of the new `Scene Bank`
+
+Direction: the new `Scene Bank` MUST persist its own Studio-owned asset format.
+
+Implications:
+
+- the `Scene Bank` is not a raw persisted `TMX` document;
+- the Studio-owned format MUST retain the identity relationships and internal references needed to regenerate `TMX` deterministically;
+- the Studio may generate and keep the corresponding `TMX` as a derived Tiled-facing artifact for the asset;
+- final pack materialization into a dedicated `assets.pa` representation is explicitly outside this wave.
+
+#### 2. Ownership of scene-asset management in `Assets`
+
+Direction: the `Assets` workspace MUST fully manage the scene-facing asset lifecycle.
+
+Implications:
+
+- `Assets` owns creation, metadata, validation, consistency checks, and asset-facing operations for the `Scene Bank`;
+- the heavy map-editing interaction is expected to occur in `Tiled`;
+- Studio-side asset management remains responsible for consistency and integration around that external editing loop.
+
+#### 3. Wave-1 parser requirement
+
+Direction: wave 1 MUST include an XML parser capable of both reading and writing `TMX` and `TSX`.
+
+Implications:
+
+- XML is the required implementation surface for this wave;
+- 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.
+
+#### 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;
+- 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.
+
+#### 5. Persistence of the Studio-only specialization flag
+
+Direction: the editorial specialization should be represented internally as an enum and stored on the Studio-controlled asset entity that already owns asset metadata.
+
+Implications:
+
+- the flag remains Studio-only and does not redefine the runtime asset family;
+- the enum should encode membership such as `Tileset (GlyphBank)`, making filtering and applicability rules explicit;
+- persistence should reuse the existing Studio/asset metadata home rather than inventing a separate document just for the specialization flag;
+- the current working assumption is that this persistence may belong alongside the asset entity already controlled by Studio tooling, pending code-level confirmation of the exact home.
+
+#### 6. Validation ownership and specialization limits in wave 1
+
+Direction: specialization should unlock Studio-specific actions, but it should NOT hard-lock general glyph-bank editing in this wave.
+
+Implications:
+
+- a specialization such as `Tileset`, `Sprites`, or `UI` primarily controls which Studio actions and flows are available for that glyph bank;
+- the base glyph-bank runtime/editor model remains flexible in wave 1;
+- consistency checks that depend on how the glyph bank is used in a map should be enforced by the `Scene Bank`;
+- this keeps wave-1 constraints aligned with the runtime flexibility instead of prematurely freezing the glyph-bank editor surface.
+
+#### 7. Diagnostic and blocking model
+
+Direction: scene and Tiled consistency issues should use the same diagnostic pattern already used by glyph assets.
+
+Implications:
+
+- invalid or unsupported references should surface as Studio diagnostics;
+- 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.
+
+#### 8. Supported Tiled feature subset in wave 1
+
+Direction: wave 1 should support `Object Layers`, properties, flips, and collisions from the start.
+
+Implications:
+
+- collisions should be supported in both places that Tiled can represent them for this workflow;
+- tile-owned collision may live in the `TSX` side of a specialized `Tileset` glyph bank;
+- map-owned collision must be represented through `Object Layer` content in the `TMX` side of the `Scene Bank`;
+- map-side `Object Group` support is useful because the pipeline will gradually absorb additional features such as collision, camera boundaries, lights, and similar scene annotations;
+- the remaining unsupported Tiled features for this wave are the broader feature set outside this accepted subset, such as infinite maps, templates, Wang sets, and animations, unless later narrowed by a follow-up decision.
+
+### Future note - possible collision-pipeline consolidation
+
+This agenda also records a possible future pipeline direction that is explicitly outside the current wave:
+
+- once collision support becomes mature enough, the pipeline may generate a canonical map-side `objectgroup` dedicated to collision, such as `collision`;
+- that generated layer could read or derive effective collision information from tile-owned collision definitions and map-authored collision content;
+- the pack pipeline could then consume that consolidated collision layer as the immediate source for collision materialization in the packed asset output.
+
+Important boundary:
+
+- this is a future optimization and publication-direction note, not a wave-1 authoring rule;
+- authored collision and generated collision layers must remain conceptually separate until a later decision formalizes that pipeline stage.
+
+### Convergence pass - accepted local UX direction
+
+#### 1. Placement of specialization-specific actions in `Assets`
+
+Recommendation: specialization-specific actions should be stacked together with the existing asset actions.
+
+Reasoning:
+
+- the current `Assets` workspace already has an established actions surface;
+- introducing a second action region between summary and actions would fragment the UX without adding a clearer ownership model;
+- specialization-specific commands remain asset actions and do not need a separate structural host.
+
+Accepted local direction for this agenda:
+
+- the `Assets` workspace MUST NOT introduce a separate action region between summary and actions for specialization-specific commands;
+- commands such as `build tileset.tsx` SHOULD appear in the same action stack as the existing asset actions;
+- 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.
 
 ## Resolution
 
 Recommended next step:
 
 - converge this agenda around a first-wave `Tiled` subset;
-- define whether the new asset type is raw-imported or normalized;
+- define whether the new scene asset is raw-imported or normalized;
+- lock the Studio-only glyph-bank specialization-flag model for `Tileset`, `Sprites`, and `UI`;
+- lock the first-wave one-tileset-per-map rule;
 - then write a replacement decision for asset ownership, parser boundary, and wave-1 scope.

test-projects/main/assets/Zelda3/primeiro tileset.tsx

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<tileset version="1.10" tiledversion="1.12.1" name="primeiro tileset" tilewidth="32" tileheight="32" tilecount="13" columns="0">
+ <grid orientation="orthogonal" width="1" height="1"/>
+ <tile id="1">
+  <image source="flag00.png" width="32" height="32"/>
+ </tile>
+ <tile id="2">
+  <image source="flag01.png" width="32" height="32"/>
+ </tile>
+ <tile id="3">
+  <image source="flag02.png" width="32" height="32"/>
+ </tile>
+ <tile id="4">
+  <image source="flag03.png" width="32" height="32"/>
+ </tile>
+ <tile id="5">
+  <image source="link00.png" width="32" height="32"/>
+ </tile>
+ <tile id="6">
+  <image source="link01.png" width="32" height="32"/>
+ </tile>
+ <tile id="7">
+  <image source="link02.png" width="32" height="32"/>
+ </tile>
+ <tile id="8">
+  <image source="link03.png" width="32" height="32"/>
+ </tile>
+ <tile id="9">
+  <image source="link04.png" width="32" height="32"/>
+ </tile>
+ <tile id="10">
+  <image source="link05.png" width="32" height="32"/>
+ </tile>
+ <tile id="11">
+  <image source="link06.png" width="32" height="32"/>
+ </tile>
+ <tile id="12">
+  <image source="link07.png" width="32" height="32"/>
+ </tile>
+ <tile id="0">
+  <properties>
+   <property name="glyph_id" type="int" value="0"/>
+  </properties>
+  <image source="../recovered/atlas2/confirm.png" width="16" height="16"/>
+  <objectgroup draworder="index" id="2">
+   <object id="1" x="4" y="4" width="8" height="8"/>
+   <object id="2" x="1.59375" y="0.15625" width="2.75" height="2.90625"/>
+  </objectgroup>
+ </tile>
+</tileset>

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

@@ -1,6 +1,6 @@
 <?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="4" nextobjectid="12">
- <tileset firstgid="1" source="primeiro tileset.tsx"/>
+<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">
+ <tileset firstgid="1" source="../Zelda3/primeiro tileset.tsx"/>
  <layer id="1" name="Tile Layer 1" width="25" height="25">
   <data encoding="csv">
 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
@@ -32,5 +32,8 @@
  </layer>
  <objectgroup id="3" name="Object Layer 1">
   <object id="11" x="16" y="16" width="64" height="64"/>
+  <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>
  </objectgroup>
 </map>

test-projects/main/assets/scenes/primeiro tileset.tsx

@@ -1,7 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<tileset version="1.10" tiledversion="1.12.1" name="primeiro tileset" tilewidth="16" tileheight="16" tilecount="1" columns="0">
- <grid orientation="orthogonal" width="1" height="1"/>
- <tile id="0">
-  <image source="../recovered/atlas2/confirm.png" width="16" height="16"/>
- </tile>
-</tileset>

test-projects/main/assets/scenes/scene1.tiled-project

@@ -1,14 +0,0 @@
-{
-    "automappingRulesFile": "",
-    "commands": [
-    ],
-    "compatibilityVersion": 1100,
-    "extensionsPath": "extensions",
-    "folders": [
-        "."
-    ],
-    "properties": [
-    ],
-    "propertyTypes": [
-    ]
-}

test-projects/main/assets/scenes/scene1.tiled-session

@@ -1,38 +0,0 @@
-{
-    "activeFile": "primeiro tileset.tsx",
-    "expandedProjectPaths": [
-        "."
-    ],
-    "fileStates": {
-        "primeiro mapa.tmx": {
-            "scale": 2.55,
-            "selectedLayer": 1,
-            "viewCenter": {
-                "x": 200,
-                "y": 200.58823529411768
-            }
-        },
-        "primeiro tileset.tsx": {
-            "dynamicWrapping": true,
-            "scaleInDock": 1,
-            "scaleInEditor": 1
-        }
-    },
-    "last.imagePath": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/test-projects/main/assets/recovered/atlas2",
-    "map.height": 25,
-    "map.lastUsedFormat": "tmx",
-    "map.tileHeight": 16,
-    "map.tileWidth": 16,
-    "map.width": 25,
-    "openFiles": [
-        "primeiro mapa.tmx",
-        "primeiro tileset.tsx"
-    ],
-    "project": "scene1.tiled-project",
-    "recentFiles": [
-        "primeiro mapa.tmx",
-        "primeiro tileset.tsx"
-    ],
-    "tileset.lastUsedFormat": "tsx",
-    "tileset.type": 1
-}