Issue #14 - [FEATURE] Preserve remote document version when saving local changes

[rogelio-cmj]

Motivation

The workspace store needs to support a local-first editing workflow where users can make changes to documents, save them locally, and later sync those changes back to a remote registry. Currently, when a document is saved, the system overwrites the original document reference, losing track of what the remote version looked like. This makes it impossible to properly sync changes back to the remote registry or to detect conflicts between local and remote versions. A proper document versioning system needs to maintain three distinct states: the original remote version, the last locally saved version, and the current in-memory working version.

Current Behavior

The workspace store maintains only two document states: the original document (before reactive wrapping) and the current reactive workspace document. When saveDocument() is called, changes are persisted directly back to the original document, overwriting the last known remote version. This means there's no way to distinguish between what came from the remote registry and what has been saved locally.

Reproduction Steps:

1. Load a document into the workspace store from a remote source
2. Make changes to the document in the reactive workspace
3. Call saveDocument() to persist the changes
4. Attempt to access the original remote version of the document
5. Observe: The original document has been overwritten with the saved changes, and the remote version is lost

Expected Behavior

The workspace store should maintain three distinct document states:

• Original documents: The pristine version as loaded from the remote registry (never modified)
• Intermediate documents: The last locally saved version (updated when saveDocument() is called)
• Workspace documents: The current in-memory reactive version (may have unsaved changes)

When saveDocument() is called, it should update the intermediate document while preserving the original. When exportDocument() is called, it should export the intermediate (locally saved) version. When syncing with a remote registry, the system should be able to compare the intermediate version against the original to determine what needs to be pushed.

Acceptance Criteria:

• A new intermediate document storage layer is introduced to track locally saved versions
• The saveDocument() method updates the intermediate document without modifying the original
• The exportDocument() method exports from the intermediate document, not the original
• The revertDocument() method reverts to the intermediate document (last saved state), not the original remote version
• Documentation is updated to clarify the three-tier document state model

Steps To Test

1. Load a document into the workspace store with known content
2. Verify the original document is stored and matches the input
3. Make changes to the reactive workspace document
4. Call saveDocument() and verify the intermediate document is updated
5. Verify the original document remains unchanged and still matches the initial input
6. Call exportDocument() and verify it returns the intermediate (saved) version, not the original
7. Make additional unsaved changes to the workspace document
8. Call revertDocument() and verify it reverts to the intermediate version, not the original
9. Verify all existing tests still pass with the new three-tier state model

Submission

Download https://cap.so/ to record your screen (use Studio mode). Export as an mp4, and drag and drop into an issue comment below.

Guide to submitting pull requests: https://hackmd.io/@timothy1ee/Hky8kV3hlx