prometeu-studio/discussion/workflow/decisions/DEC-0026-studio-scene-workspace.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0026	studio-scene-workspace	Scene Workspace Ownership and Wave-1 Tilemap Scope	abandoned	2026-04-14	2026-04-14	AGD-0029	PLN-0049 PLN-0050 PLN-0051 PLN-0052	studio workspace scene tilemap asset runtime-alignment

Decision

The Studio SHALL introduce a dedicated Scene Workspace as a first-class shell workspace for scene authoring.

The Scene Workspace MUST own the authoring lifecycle of scenes as scenes, not as asset-detail forms.

The Studio SHALL treat the edited scene as an intermediate authoring artifact owned by the Scene Workspace.

The Scene Workspace MAY create a new scene and, as part of that flow, create the corresponding SCENE asset.

The Assets workspace MAY also create a SCENE asset, but it MUST NOT paint tilemaps, edit scene content, choose scene tilesets, or own other editorial scene configuration.

When a SCENE asset is created from Assets, authoring and subsequent editing MUST be delegated to the Scene Workspace.

The first implementation wave of the Scene Workspace SHALL expose only the Tilemap aspect.

The wave-1 Tilemap aspect MUST support:

• a left scene navigator;
• a central map editing surface;
• a right-side tilemap details area with dimensions and layer-relevant detail;
• a tile palette area for tile selection and painting;
• four canonical scene layers;
• independent layer dimensions;
• scene-first navigation;
• explicit tile presence semantics aligned with the runtime model;
• basic painting, erasing, tile selection, layer visibility, and layer focus.

The wave-1 Scene Workspace MUST NOT include:

• authoring for camera boundaries;
• authoring for lights;
• authoring for AABB data;
• placeholder tabs that imply those capabilities already exist;
• advanced paint tools such as marquee, bucket fill, flood fill, or equivalent higher-order tooling.

The Scene Workspace MUST use an explicit and stable binding between the intermediate scene artifact and the corresponding SCENE asset.

That binding MUST NOT rely on path inference as its primary semantic anchor.

The Scene Workspace MUST own editorial tileset selection for the scene.

Any technically valid glyph bank MAY be referenced as a tileset under the scene-authoring model.

Optional Studio-only curation such as tagging glyph banks for better discoverability MAY exist, but it MUST NOT redefine the underlying capability contract.

Rationale

This decision separates two different responsibilities that would otherwise collapse into one another:

• scene authoring as an editorial workspace concern;
• asset management as an asset-first Studio concern.

Keeping the Scene Workspace independent prevents the Assets workspace from becoming a generic container for heavy domain editors.

That separation also matches the user-facing intent:

• the Assets workspace can create or surface a SCENE asset;
• the Scene Workspace is where the user actually authors the scene.

Wave 1 is intentionally narrow.

The goal is to prove the canonical scene-authoring loop around tilemaps, layers, tileset selection, and save semantics before introducing additional aspect domains such as camera, lights, or collision-adjacent editing.

The decision also keeps the Studio aligned with the runtime model already present in ../runtime:

• four canonical layers;
• per-layer tilemaps with independent dimensions;
• explicit tile presence rather than magic empty glyph ids;
• no leakage of viewport-cache or transient renderer concerns into authoring ownership.

Technical Specification

1. Workspace Topology

• The Studio shell MUST mount Scene Workspace as its own workspace entry.
• The Scene Workspace MUST follow the same shell/workspace separation rules as other Studio workspaces.
• The Scene Workspace MUST own its operational detail locally rather than pushing it into shell-global surfaces.

2. Scene Ownership Model

• A scene edited in Scene Workspace MUST be treated as a Studio-owned intermediate authoring artifact.
• The scene authoring artifact MUST have its own stable identity.
• The scene authoring artifact MUST be the primary navigation unit inside the Scene Workspace.
• The related SCENE asset MUST appear only as linked context, status, or action, not as the primary navigation unit of the workspace.

3. Relationship with Assets

• Assets MAY create a SCENE asset.
• Scene Workspace MAY create a SCENE asset as part of creating a new scene.
• Assets MUST delegate scene-content authoring to Scene Workspace.
• Assets MUST NOT expose map painting or equivalent scene-editor interactions.
• The Studio SHOULD support contextual handoff from Assets to Scene Workspace after SCENE asset creation.

4. Binding Contract

• The relationship between a scene authoring artifact and a SCENE asset MUST be explicit.
• The primary binding anchor MUST be Studio metadata or equivalent explicit identity linkage.
• Path MAY be retained as secondary location context.
• Rename or relocation MUST NOT silently break semantic linkage solely because paths changed.

5. Wave-1 UI Composition

• The left region MUST provide a scene navigator inspired by the custom-navigation discipline used in Assets, but it MUST remain scene-first rather than asset-first.
• The top region of the workspace MUST provide an aspect-tab structure.
• Wave 1 MUST expose only one visible tab: Tilemap.
• The central region of the Tilemap tab MUST host the editable map canvas.
• The right-side upper region MUST show tilemap dimensions and relevant details for the active scene/layer context.
• The right-side lower region MUST show the tile palette used for picking and painting.

6. Scene Model Expectations for Wave 1

• The workspace MUST model exactly four scene layers.
• Each layer MUST support independent dimensions.
• Each layer MUST be editable in a way compatible with the runtime-aligned canonical scene model.
• The workspace MUST NOT flatten all layers into one synthetic shared-size map contract.

7. Tileset Rules

• Tileset choice MUST be owned by Scene Workspace.
• The workspace MAY resolve tileset selection per scene or per layer, as long as the chosen model remains explicit and internally consistent.
• Any glyph bank that is technically valid for use as tileset data MAY be selected.
• Optional Studio editorial tagging MAY improve filtering and discoverability, but MUST remain non-normative to the base capability.
• Assets MUST NOT override editorial tileset selection from the scene workspace.

8. Editing and Save Rules

• The Scene Workspace MUST save the intermediate scene authoring artifact through its own save flow.
• Saving the scene authoring artifact MUST remain distinct from asset creation or asset-management flows.
• The workspace MUST support a normal save-oriented document/editing lifecycle for the scene artifact rather than an asset-form apply/reset lifecycle.

9. Tooling Scope for Wave 1

• Wave 1 MUST support basic painting.
• Wave 1 MUST support erasing through explicit tile presence control.
• Wave 1 MUST support selecting a tile and palette for painting.
• Wave 1 MUST support layer visibility.
• Wave 1 MUST support layer focus.
• Wave 1 MUST NOT depend on bucket fill, marquee, flood fill, or equivalent advanced editing tools.

10. Tile Semantics

• Tile absence MUST be represented by explicit presence state.
• glyph_id = 0 MUST remain a valid glyph identifier.
• Erasing a tile MUST clear presence state instead of writing a magic empty glyph value.
• Painting behavior MUST operate over explicit tile data such as active state, glyph id, palette id, and flip state.

Constraints

• This decision is limited to the Scene Workspace and its Studio-local boundary with Assets.
• This decision MUST NOT be used to infer packer publication rules beyond the existence of a linked SCENE asset.
• This decision MUST NOT be treated as approval for camera, lighting, AABB, or other future aspect tabs.
• Any future change to the ownership boundary between Scene Workspace and Assets requires an explicit revision or replacement decision.
• Any future change to the stable binding contract between scene artifact and SCENE asset requires an explicit revision or follow-up decision.

Revision Log

• 2026-04-14: Initial accepted decision from AGD-0029.
• 2026-04-15: Abandoned by explicit user request before implementation completion; follow-up work must proceed through a new discussion rather than this decision.