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 setup and restoration state

Purpose

Define the normative contract for the main project-local Studio state store.

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 state store MUST be owned by StudioProjectSession, or by a service explicitly owned by StudioProjectSession.
3. The main store MUST start as a single file.
4. The main store MUST be versioned.
5. The main 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 store MUST save when the project shell or project session closes.
8. Missing, invalid, or schema-incompatible state MUST fall back to safe default values and MUST NOT block project open.

Accepted Wave-1 Categories

The main store MUST include:

• projectLocalSetup
• shellLayout
• openShellState
• editorRestoration

Wave-1 accepted meaning is:

• projectLocalSetup: project-local Studio setup required to operate on the project, including runtime paths such as the Prometeu runtime path;
• 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.

Explicit Exclusions

The main store MUST NOT include:

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

Project-local activity may still live under .studio/, but it is a separate persistence concern and not part of the main store defined here.

Ownership Rules

• shell and workspace UI may consume the main 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.

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.