studio session persistent

This commit is contained in:
2026-04-04 07:34:49 +01:00
parent a824b2185f
commit eb2520fa40
23 changed files with 815 additions and 994 deletions
@@ -8,11 +8,12 @@ Active
- `prometeu-studio`
- Studio project-session persistence under `.studio/`
- project-local Studio setup and restoration state
- project-local Studio session restoration state
- project-local Studio setup configuration
## Purpose
Define the normative contract for the main project-local Studio state store.
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
@@ -26,47 +27,63 @@ It extends:
## 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.
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 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.
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 store MUST include:
The main session-restoration 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.
## 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 store MUST NOT include:
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 project-local setup or restoration state.
- recomputable results that do not represent session 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.
`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 store through project-session-owned contracts;
- 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 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