prometeu-studio/docs/specs/studio/8. Project-Local Studio State Specification.md

Project-Local Studio State Specification

Status

Active

Applies To

• prometeu-studio
• Studio project-session persistence under .studio/
• project-local Studio session restoration state
• project-local Studio setup configuration

Purpose

Define the normative contract for Studio project-local persistence under .studio/, including the boundary between the main session-restoration store and the dedicated setup configuration file.

Authority and Precedence

This specification implements the accepted decision for project-local Studio state under .studio/.

It extends:

• 1. Studio Shell and Workspace Layout Specification.md
• 5. Code Editor Workspace Specification.md

Core Rules

1. The canonical root for project-local Studio persistence MUST be .studio/ in the project root.
2. The main project-local Studio session-restoration store MUST be owned by StudioProjectSession, or by a service explicitly owned by StudioProjectSession.
3. The main session-restoration store MUST remain a single file at .studio/state.json.
4. The main session-restoration store MUST be versioned.
5. The main session-restoration store MUST load when the project session opens.
6. Restorable shell and editor state accepted by this wave MUST restore when the project shell mounts.
7. The main session-restoration store MUST save when the project shell or project session closes.
8. Missing, invalid, or schema-incompatible session-restoration state MUST fall back to safe default values and MUST NOT block project open.
9. Project-local setup configuration MUST live in a separate file at .studio/setup.json.
10. Project-local setup MUST NOT participate in the .studio/state.json snapshot lifecycle.
11. Project-local setup MUST be read through a dedicated DTO/file boundary when a consumer needs it.

Accepted Wave-1 Categories

The main session-restoration store MUST include:

• shellLayout
• openShellState
• editorRestoration

Wave-1 accepted meaning is:

• shellLayout: restorable layout state already accepted by implementation, including divider positions and equivalent layout proportions for accepted workspaces such as Assets and Code Editor, Project Navigator expansion state, and editor dock-panel open/closed plus restored-size configuration;
• openShellState: which workspace or equivalent shell-owned project view was open;
• editorRestoration: open editor tabs and active tab.

Project-Local Setup Configuration

Project-local setup is a separate persistence concern under .studio/.

Rules:

• project-local setup MUST live in .studio/setup.json;
• project-local setup MUST be treated as project configuration rather than session state;
• project-local setup MAY contain runtime-oriented values such as the Prometeu runtime path;
• project-local setup MAY grow with additional manual or automatic configuration keys over time;
• consumers such as Play MUST read project-local setup from the dedicated setup file rather than from .studio/state.json;
• this revision uses a dry format change and MUST NOT preserve compatibility with the obsolete shape where projectLocalSetup was embedded in .studio/state.json.

Explicit Exclusions

The main session-restoration store MUST NOT include:

• project-local setup configuration;
• project-local activity history;
• derived cache;
• transient hover-only or equivalent ephemeral UI state;
• heavy operational output;
• recomputable results that do not represent session restoration state.

Project-local activity and project-local setup may still live under .studio/, but they are separate persistence concerns and not part of the main session-restoration store defined here.

Ownership Rules

• shell and workspace UI may consume the main session-restoration store through project-session-owned contracts;
• shell and workspace UI must not define competing primary persistence files for accepted wave-1 categories;
• project-local setup may be consumed before a dedicated settings UI exists;
• project-local setup readers must not turn the setup file into another session snapshot by convenience.

Non-Goals

• defining persistence for project-local activity
• introducing a multi-file main store in this wave
• defining a settings editor UI for project-local setup
• persisting arbitrary transient workspace detail by convenience

Exit Criteria

This specification is complete enough when:

• the .studio/ boundary is unambiguous;
• accepted and excluded categories are explicit;
• load, restore, save, and fallback timing are explicit;
• and the ownership boundary with StudioProjectSession is normatively locked.