studio session persistent
This commit is contained in:
+147
@@ -0,0 +1,147 @@
|
||||
---
|
||||
id: LSN-0031
|
||||
ticket: studio-project-local-studio-state-under-dot-studio
|
||||
title: Project-Local Studio State and Lifecycle-Safe Layout Restoration
|
||||
created: 2026-04-04
|
||||
tags: [studio, project-session, project-state, persistence, dot-studio, shell, layout, setup, javafx]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Studio needed a real project-local persistence boundary for user organization and setup.
|
||||
The team wanted the opened project itself to carry Studio-local state under `.studio/`, including:
|
||||
|
||||
- project-local setup such as the Prometeu runtime path,
|
||||
- shell and workspace organization,
|
||||
- open editor tabs and the active tab,
|
||||
- and restorable workspace layout such as split pane positions and mini-panel visibility.
|
||||
|
||||
The discussion explicitly rejected mixing that concern with global launcher preferences or with project-local activity history.
|
||||
It also rejected treating every UI surface as an independent persistence owner.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Make `.studio/` the Canonical Project-Local Studio Root
|
||||
|
||||
**What:**
|
||||
The durable Studio state for one opened project now lives under `.studio/` in the project root, with a single-file main store at `.studio/state.json`.
|
||||
|
||||
**Why:**
|
||||
That makes project-local setup and organization travel with the project instead of leaking into application-global storage.
|
||||
It also gives Studio one canonical place to evolve project-local state over time.
|
||||
|
||||
**Trade-offs:**
|
||||
The single-file approach is simpler to maintain and migrate in the first wave, but it concentrates multiple categories into one schema that must stay disciplined.
|
||||
|
||||
### Keep `StudioProjectSession` as the Persistence Owner
|
||||
|
||||
**What:**
|
||||
`StudioProjectSession` owns loading and saving of the main project-local Studio store.
|
||||
Workspaces and shell surfaces may consume and update in-memory snapshots, but they do not redefine the persistence lifecycle.
|
||||
|
||||
**Why:**
|
||||
The opened project session is the real lifetime of per-project Studio state.
|
||||
That state must survive workspace switching while still remaining scoped to one opened project window.
|
||||
|
||||
**Trade-offs:**
|
||||
This adds an explicit project-session boundary, but that is better than letting shell views or workspaces become accidental persistence roots.
|
||||
|
||||
### Split Main Session State from Project-Local Activity
|
||||
|
||||
**What:**
|
||||
The main store covers `projectLocalSetup`, `shellLayout`, `openShellState`, and `editorRestoration`.
|
||||
Project-local activity remains under `.studio/`, but outside the main session store and with its own persistence policy.
|
||||
|
||||
**Why:**
|
||||
Layout and setup are snapshot-like session restoration concerns.
|
||||
Activity is more naturally log-like and should not distort the main contract.
|
||||
|
||||
**Trade-offs:**
|
||||
This introduces two project-local persistence shapes under `.studio/`, but it keeps the session store narrow and predictable.
|
||||
|
||||
### Treat JavaFX Layout Restore as a Lifecycle Problem, Not Just a Codec Problem
|
||||
|
||||
**What:**
|
||||
The final implementation had to restore split pane state only when the relevant JavaFX surfaces were actually ready, suppress state capture while applying the restore, and reapply pending layout after the project stage was shown.
|
||||
|
||||
**Why:**
|
||||
The persisted values were being loaded correctly, but JavaFX initialization and default layout passes could still overwrite them with default divider positions such as `0.35`.
|
||||
The real bug was lifecycle ordering, not file persistence.
|
||||
|
||||
**Trade-offs:**
|
||||
The implementation became slightly more explicit about initialization phases, but it avoided unreliable "save more often" workarounds and kept the persistence lifecycle simple.
|
||||
|
||||
## Final Implementation
|
||||
|
||||
The final implementation established a project-local Studio state contract across specs, code, and tests:
|
||||
|
||||
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` now defines shell restore/save behavior around the project session.
|
||||
- `docs/specs/studio/5. Code Editor Workspace Specification.md` now treats cross-session editor restoration as part of the accepted contract.
|
||||
- `docs/specs/studio/8. Project-Local Studio State Specification.md` defines the `.studio` root, the single-file main store, wave-1 categories, exclusions, and fallback behavior.
|
||||
- `ProjectLocalStudioState` and `ProjectLocalStudioStateService` define the versioned single-file state model at `.studio/state.json`.
|
||||
- `StudioProjectSession` and `StudioProjectSessionFactory` own load/save lifecycle for the state store.
|
||||
- `MainView`, `EditorWorkspace`, and `AssetWorkspace` restore layout from the session-owned snapshot and keep the in-memory snapshot synchronized during the session.
|
||||
- layout save remains lifecycle-driven: update memory on change, save on workspace switch, save on project close, load on project open, and apply on workspace open.
|
||||
- fallback to safe defaults keeps project open resilient when `.studio/state.json` is absent, invalid, or incompatible.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
### Pattern: Put Project-Scoped UI Persistence Under the Project Session
|
||||
|
||||
When Studio state belongs to one opened project but must survive workspace focus changes, the owner should be a project session object.
|
||||
That is the right boundary for:
|
||||
|
||||
- project-local setup,
|
||||
- restorable shell/workspace layout,
|
||||
- open workspace selection,
|
||||
- and editor restoration state.
|
||||
|
||||
### Pattern: Keep Persistence Lifecycle Simple and Explicit
|
||||
|
||||
The durable lifecycle is:
|
||||
|
||||
1. load on project-session open,
|
||||
2. apply on workspace mount,
|
||||
3. keep the latest state in memory during the session,
|
||||
4. save on workspace switch,
|
||||
5. save on project or Studio close.
|
||||
|
||||
This is better than broad autosave logic when the accepted contract only needs stable session restoration.
|
||||
|
||||
### Pattern: Reapply Layout Only After the UI Surface Is Real
|
||||
|
||||
For JavaFX `SplitPane` and docked layout surfaces, correct restoration requires more than reading the saved divider values.
|
||||
The implementation must:
|
||||
|
||||
- defer application until the control has real dimensions,
|
||||
- suppress state-capture callbacks while restore is in progress,
|
||||
- and reapply pending layout after stage show if the initial layout pass can still override the restored values.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Do not push project-local Studio state into launcher-global preferences just because there is no UI for editing all categories yet.
|
||||
- Do not let individual workspaces or panels become persistence owners; they should only expose capture and restore snapshots.
|
||||
- Do not mix project-local activity history into the main session restoration file.
|
||||
- Do not "fix" layout restore bugs by adding generic debounce-based save behavior when the real issue is UI lifecycle ordering.
|
||||
- Do not capture layout again during teardown if the session already has the correct in-memory snapshot; late teardown capture can overwrite valid persisted values with defaults.
|
||||
|
||||
## References
|
||||
|
||||
- `DEC-0016` Project-local Studio state under `.studio`
|
||||
- `PLN-0037` Project-local Studio state store and restoration
|
||||
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
|
||||
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
|
||||
- `docs/specs/studio/8. Project-Local Studio State Specification.md`
|
||||
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioState.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioStateService.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/window/MainView.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Project-local Studio organization belongs under `.studio/`, not in global app state.
|
||||
- `StudioProjectSession` is the correct owner for per-project Studio persistence.
|
||||
- JavaFX layout restoration succeeds only when persistence and UI lifecycle are aligned, not when persistence is merely present.
|
||||
+136
@@ -0,0 +1,136 @@
|
||||
---
|
||||
id: LSN-0032
|
||||
ticket: studio-project-local-setup-separate-from-main-studio-state
|
||||
title: Separate Project Config from Session Restoration State
|
||||
created: 2026-04-04
|
||||
tags: [studio, project-session, project-state, persistence, dot-studio, setup, configuration, boundary]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Studio had already introduced project-local persistence under `.studio/`, with a main single-file store at `.studio/state.json`.
|
||||
That first wave correctly established project-local session restoration, but it also embedded `projectLocalSetup` in the same file.
|
||||
|
||||
After implementation and real lifecycle testing, the boundary problem became clearer:
|
||||
|
||||
- `shellLayout`, `openShellState`, and `editorRestoration` are session-restoration state;
|
||||
- runtime path and similar project-local settings are configuration of the project itself;
|
||||
- those two categories do not share the same lifecycle, mutation model, or troubleshooting surface.
|
||||
|
||||
The revision work closed that mismatch by splitting project configuration from session restoration while keeping both under `.studio/`.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Separate Project-Local Setup from `.studio/state.json`
|
||||
|
||||
**What:**
|
||||
`projectLocalSetup` was removed from the main session-restoration state contract.
|
||||
The main store now remains focused on:
|
||||
|
||||
- `shellLayout`
|
||||
- `openShellState`
|
||||
- `editorRestoration`
|
||||
|
||||
Project-local setup now lives in its own file at `.studio/setup.json`.
|
||||
|
||||
**Why:**
|
||||
Session restoration is about reopening the Studio shell in the last accepted project-local shape.
|
||||
Project setup is about durable configuration that consumers such as `Play` may need independently from shell/session restore behavior.
|
||||
|
||||
Those concerns belong to the same project-local root, but not to the same file or lifecycle contract.
|
||||
|
||||
**Trade-offs:**
|
||||
This adds another persisted file under `.studio/`.
|
||||
That extra file is worth it because it prevents `state.json` from becoming an accidental catch-all store and gives project configuration a clearer operational identity.
|
||||
|
||||
### Keep Setup Out of the Session Snapshot Lifecycle
|
||||
|
||||
**What:**
|
||||
The setup file is read through a dedicated DTO/service boundary and is intended for on-demand consumption.
|
||||
It does not participate in the in-memory snapshot lifecycle used by `.studio/state.json`.
|
||||
|
||||
**Why:**
|
||||
Project configuration is not session state.
|
||||
Treating it as another session snapshot would blur the boundary again and recreate the same design problem in a different shape.
|
||||
|
||||
**Trade-offs:**
|
||||
Consumers must explicitly read the setup file instead of receiving it “for free” from session-state snapshots.
|
||||
That is an intentional cost because it preserves the correct mental model and ownership.
|
||||
|
||||
### Use a Dry Format Change for Early Boundary Repair
|
||||
|
||||
**What:**
|
||||
The revision intentionally did not add compatibility for the obsolete shape where `projectLocalSetup` was embedded in `.studio/state.json`.
|
||||
|
||||
**Why:**
|
||||
The goal of this wave was to repair the boundary cleanly, not to carry transitional compatibility machinery for a very recent format that had not yet earned long-term support cost.
|
||||
|
||||
**Trade-offs:**
|
||||
Existing local fixtures and test projects had to be updated directly.
|
||||
That is acceptable for a controlled early-stage format revision.
|
||||
|
||||
## Final Implementation
|
||||
|
||||
The Studio domain now uses two different project-local persistence files under `.studio/`:
|
||||
|
||||
- `.studio/state.json` for session-restoration state only;
|
||||
- `.studio/setup.json` for project-local configuration.
|
||||
|
||||
The implementation changes established that split across code, tests, and specs:
|
||||
|
||||
- `ProjectLocalStudioState` and `ProjectLocalStudioStateService` no longer include `projectLocalSetup`.
|
||||
- `ProjectLocalStudioSetup` and `ProjectLocalStudioSetupService` define the dedicated setup DTO and reader.
|
||||
- `ProjectStudioPaths` now exposes the dedicated `.studio/setup.json` path.
|
||||
- the Studio specs now describe setup as project configuration rather than session state.
|
||||
- test projects under `test-projects/` now include the dedicated `setup.json` file.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
### Pattern: One Project-Local Root, Multiple Persistence Contracts
|
||||
|
||||
It is valid for several project-local persistence files to live under the same `.studio/` root when they represent different categories:
|
||||
|
||||
- session-restoration snapshots;
|
||||
- project configuration;
|
||||
- activity history;
|
||||
- or other future categories.
|
||||
|
||||
The important rule is not “one root means one file”.
|
||||
The important rule is that each file must have a clear semantic contract.
|
||||
|
||||
### Pattern: Separate Snapshot State from Durable Config
|
||||
|
||||
If data is restored through open/mount/close lifecycle behavior, it is snapshot state.
|
||||
If data configures how the project should behave when some consumer needs it, it is durable config.
|
||||
|
||||
Those categories should not share the same file by convenience.
|
||||
|
||||
### Pattern: Read Config on Demand
|
||||
|
||||
When configuration does not belong to the session snapshot lifecycle, use a narrow reader boundary and let consumers fetch it when needed.
|
||||
That keeps configuration from being accidentally reclassified as runtime session state.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Do not let `state.json` become a generic “everything under `.studio/`” store.
|
||||
- Do not move project-local setup into global application preferences just to avoid another file.
|
||||
- Do not turn the dedicated setup file back into a session snapshot by caching it in the same lifecycle as layout restoration.
|
||||
- Do not add compatibility machinery reflexively when the real need is to fix a still-young boundary cleanly.
|
||||
- Do not leave the setup file name ambiguous across code and specs; the implementation should choose one explicit canonical name and use it consistently.
|
||||
|
||||
## References
|
||||
|
||||
- `DEC-0017` Separate project-local setup from session restoration state under `.studio/`
|
||||
- `PLN-0038` Separate project-local setup from session restoration state
|
||||
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
|
||||
- `docs/specs/studio/8. Project-Local Studio State Specification.md`
|
||||
- `prometeu-studio/src/main/java/p/studio/projects/ProjectStudioPaths.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioState.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioSetup.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioSetupService.java`
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Project-local persistence under `.studio/` does not imply a single-file design.
|
||||
- Session restoration state and project configuration are different persistence categories and should stay separate.
|
||||
- A small, explicit config reader is often better than folding durable configuration into a session snapshot contract.
|
||||
Reference in New Issue
Block a user