Proposal: make project save state explicit and consistent

[hcoona]

Goal

The common project save flow works well today, but hcoona#17 describes several edge cases where different parts of the app appear to interpret "saved" slightly differently.

The goal of this proposal is not to redesign the project file format or introduce a large new persistence system. The goal is smaller: make the save-state decisions explicit, shared, and tested so that the window title, Save/Ctrl+S, close/switch confirmation, autosave, and actual file persistence all agree.

Observed problem

Today, the project's undo version and last saved version work as a reasonable dirty-state proxy for the normal path:

1. Open an existing project.
2. Edit it.
3. Save it back to the same file.

The edge cases are different. A project can have no new undo edits but still not be safely represented by the main project file. For example:

• the project has no file name yet;
• the attached project file was deleted or is missing;
• the current contents came from a newer autosave and have not been written back to the main file;
• autosave paths can accidentally become part of later save/autosave decisions.

Those cases are not all the same UX problem. "Can the user save?", "Should the title show a dirty marker?", and "Should closing warn the user?" are related, but they should not necessarily be the same boolean.

Proposed direction

I suggest centralizing the save-state logic into a small set of derived decisions on Project, or into a small value object if that is cleaner. The exact shape is less important than making the decisions explicit and tested.

A lightweight model could track:

• whether the project has a main save target;
• whether the current content differs from the last explicit save;
• whether the main save target is known to be missing;
• whether the project was restored from a newer autosave;
• whether an untitled project is still the initial blank project or has user edits.

From that, the UI can derive separate decisions:

Decision	Suggested meaning
CanSave	Save/Ctrl+S should do something useful: Save As for untitled projects, write dirty content, recreate a missing file when possible, or write recovered autosave content back to the main file.
ShowsDirtyMarker	The current content is not safely represented by the main project file.
ShouldWarnBeforeDiscard	Continuing could lose meaningful project content or recovered autosave data.
ShouldAutosave	Autosave may protect dirty content, but autosave alone should not count as an explicit save to the main project file.

Proposed user-visible behavior

Scenario	Proposed behavior
Untitled blank project	Save may open Save As, but the title does not need a dirty marker and closing does not need a warning.
Untitled project with user edits	Save opens Save As, the title shows dirty state, and close/switch prompts before discarding.
Existing clean project	Save can be disabled, no dirty marker, no close/switch prompt.
Existing dirty project	Save is enabled, the title shows dirty state, and close/switch prompts.
Attached file is missing	Save should try to write back to the original path when possible. If that fails, the app should keep the unsaved state and fall back to Save As or an error path.
Newer autosave was restored	The project should remain in a "needs explicit save" state until the recovered content is saved to the main file or saved elsewhere.
Save As is canceled	The project state should remain unchanged; dirty/recovered/missing-file state should not be cleared.

Important details

A few details seem important for correctness:

• Autosave should not clear the explicit-save state. It protects the user from data loss, but it should not make the main project file count as saved.
• Restoring from *-autosave-N.yafc should keep the main project file as the save target, rather than turning the autosave file into the project's normal path.
• Saving should not short-circuit only because the undo version matches. If the target file is missing, Save still needs to write the file.
• Existing behavior such as flushing pending undo/edit batches before persistence should be preserved.
• File-system checks should be treated carefully. Whether a target can be written is ultimately known at save time, so failed saves should leave the project in a state where the user can retry or use Save As.

Owner decisions

I think the main product decisions for the project owners are:

1. Should a brand-new untitled blank project have Save enabled, or should Save only become enabled after edits?
2. Should the title * mean "content has user edits" or the broader "main project file does not safely represent the current content"?
3. When an attached file is missing, should Ctrl+S first try to recreate the original path, immediately prompt Save As, or show an error first?
4. After autosave recovery, should Save overwrite the main file directly, or should the UI make the recovery state more explicit before overwriting?
5. What counts as a meaningful edit for an untitled project: only user-created project changes, or also automatic/default project initialization?

My preference is:

• untitled blank projects should be saveable but not dirty;
• untitled edited projects should behave like normal unsaved work;
• recovered autosave content should require an explicit save;
• missing attached files should not be treated as clean.

Practical implementation path

This can be kept incremental:

1. Add model-level tests for the save-state edge cases in Review save-state edge-case branch for upstream PR hcoona/yafc-ce#17.
2. Add a small set of derived save-state properties, or a small value object, without changing the project file format.
3. Update MainScreen to use those derived decisions for Save/Ctrl+S, the title marker, close/switch confirmation, and autosave.
4. Add tests or manual verification for Save As cancelation, missing-file save, autosave recovery, and current-project autosave paths.
5. Keep the PR focused on behavior consistency rather than a broad persistence rewrite.

This could be one PR if the change stays small, or split into a model/test PR followed by UI wiring if that is easier to review.

[hcoona]

One clarification: I think this is slightly more than a UX consistency issue. It is a small save-state modeling issue.

The user-visible questions are things like whether Save is enabled, whether the title shows *, and whether closing should warn. But those decisions are currently inferred from lower-level facts such as the undo version, attached file name, autosave path, and file existence.

The distinction I think would help is:

• save-state facts: has no save target, target file is missing, content differs from the last explicit save, content was restored from autosave, or the project is still an initial untitled blank project;
• user-facing decisions: CanSave, ShowsDirtyMarker, ShouldWarnBeforeDiscard, and ShouldAutosave.

That distinction is why I would avoid a single NeedsSave boolean carrying all of the behavior. Some states are saveable without needing a close warning, and some states need an explicit save even if there are no new undo edits.

I am not suggesting a large persistence rewrite. The smaller architecture goal is to make these rules explicit, named, and tested, so the edge cases do not depend on each UI path reinterpreting the same low-level fields.

[veger]

Some thoughts on this, mostly agreeing with the structural direction but pushing back on part of the framing.

On the dirty marker, I think it should mean exactly "the in-memory content differs from the last explicit save." That's a function of the model alone (undo position vs lastSavedVersion). A clean, newly created project has nothing in its undo buffer, so it wouldn't show a marker. That matches what most editors do, and it keeps the signal predictable.

whether the main project file does not safely represent the current content

I'd avoid this framing. It pulls filesystem state into a UI signal, and I can't think of a mainstream application that polls disk to decide whether a buffer is dirty. If the user deletes the file from under YAFC, I'd rather discover that at save time and surface an error (or fall back to Save As) than silently flip the title because a background check noticed. Disk state is the user's responsibility, not the app's to track.

That said, there's a real bug in the current Save path that's worth fixing independently. At Yafc.Model/Model/Project.cs:190:

if (lastSavedVersion == projectVersion && fileName == attachedFileName) {
// skips the write
}

Save should always attempt the write and let the OS report failure if the file is gone. That's a small correctness fix that doesn't need any new model around it.

The autosave-restore case is the one scenario where I think the model genuinely needs a small change. If YAFC opens a newer -autosave-N.yafc instead of the main file, the in-memory content really does differ from what's in the main .yafc on disk. One clean way to express that is to bump projectVersion past lastSavedVersion at load time when restoring from autosave, so the existing dirty-marker logic just works without a new property.

I would avoid a single NeedsSave boolean carrying all of the behavior. Some states are saveable without needing a close warning, and some states need an explicit save even if there are no new undo edits.

On the structural side, I agree with this, and I'd happily see the four derived decisions (CanSave, ShowsDirtyMarker, ShouldWarnBeforeDiscard, ShouldAutosave) land as a cleanup. Today the title-bar logic in MainScreen.cs:493, the close confirmation around :501-505, and the Save short-circuit in Project.cs:190 each re-derive their answer from raw fields. Centralizing those into four named properties on Project means every UI path asks the same question and gets the same answer, which is the actual consistency win the issue is after.

With the simpler semantics, the four properties stay small:

• CanSave: there are unsaved changes, or there's no save target yet.
• ShowsDirtyMarker: undo position differs from the last explicit save.
• ShouldWarnBeforeDiscard: same as ShowsDirtyMarker.
• ShouldAutosave: ShowsDirtyMarker and autosave is enabled.

No File.Exists anywhere. The filesystem edge cases collapse into "Save attempts the write, the OS reports the error."

[DaleStan]

Proposed user-visible behavior

How does this differ from the current behavior?

Should a brand-new untitled blank project have Save enabled, or should Save only become enabled after edits?

I'm now thinking Save should always be enabled. This would remove the CanSave property (it's always true) and reverse part of #594.

Should the title * mean "content has user edits" or the broader "main project file does not safely represent the current content"?

It should be equivalent to "User will be prompted to Save (As) when closing." This is almost, but not quite "the in-memory content differs from the last explicit save". A newly-created project has one item in its undo buffer when the Milestones window opens, which shouldn't count for Save prompting purposes.

When an attached file is missing, should Ctrl+S first try to recreate the original path, immediately prompt Save As, or show an error first?

I agree with @veger on ignoring the filesystem state until the OS yells at us. If we care about the filesystem state, we should enforce it by holding the file open with appropriate sharing permissions. Even if we do that, a network going offline or a USB drive being removed could defeat our efforts.

If the file is missing, recreate it. If the directory is missing, the file is read-only, or the file was deleted and a directory with the same name was created, display an error and/or prompt for Save As.
The ideal behavior when switching to Save As might be a "Retry/Cancel/Save As" prompt, or it might be immediately opening a Save As prompt initialized (if possible) so that clicking Save does a Retry.

After autosave recovery, should Save overwrite the main file directly, or should the UI make the recovery state more explicit before overwriting?

I would like autosave recovery to silently return to writing the original file. On the other hand, MS Office forces you to explicitly Save As over the original file, and presumably they made that decision for a reason.

What counts as a meaningful edit for an untitled project: only user-created project changes, or also automatic/default project initialization?

Hmmm... @veger's right that most programs let you close a new file without a save prompt. I'd like to follow that rule, which means that the change from no milestones to the automatically-selected Milestones is not meaningful.
The menus aren't accessible until the initial Milestones window is closed, but I'd still say the change usually made by the initial Milestones window is meaningful: If the user ended up with the wrong mod pack, they can close that window without unlocking any milestones, and it won't add an undo entry.

ShouldAutosave: ShowsDirtyMarker and autosave is enabled.

ShowsDirtyMarker isn't relevant to autosave. If I make a change (causing ShowsDirtyMarker == true) and let an autosave happen, ShouldAutosave should become false until I make more changes. If I then undo the change, ShowsDirtyMarker should become false but ShouldAutosave should become true.