History Subsystem

Summary

A description of the history store and how to call actions that update it appropriately.

Overview

For each document, the history store maintains a list of known past and future history states. If the state was created within Design Space, the history store also captures a snapshot of the Document and DocumentExport models at that point in time. When performing an undo/redo to a particular state, if the document is cached it will be loaded into the document store. Otherwise, in the case of history states created in standard photoshop or after some failure which caused the history store to be flushed, and therefore not containing a cached document snapshot, updateDocument is called to obtain a fresh model.

History states can be created by one of three basic patterns:

1: PS initiates a change (Rogue)

Example: An on-canvas layer move. In these cases get two events: the specific change event, and a historyState event. When handling the specific event (e.g. "move" event), unless it is guaranteed that the historyState event will be handled first, then you must use the "amendRogue" flag in the payload or use the helper action newHistoryStateRogueSafe to create the state. This will allow the history state to be amended if it was the result of a rogue event, or created otherwise.

2: DS initiated "optimistic" change

Here the action can, independent of calling photoshop, emit a single flux event which is handled by both the document store and the history store.

3: DS initiated "non optimistic" change

The action makes a change in photoshop but then has to parse the play results, or perform some separate "queries" (eg, resetBounds), before updating our model accordingly. A history state should be created as early as possible, such as with the convenience action newHistoryState, and then the subsequent events should amend the history state. Note that resetBounds, resetLayers and resetIndex all amend history in this way.

Subtitles

A note about historyState events: We currently receive historyState events in most cases. In some cases for scenario 2 and 3, we have lazily relied on the historyState event to increment the history store. For PS reasons, we may soon move away from getting these events if they are a result of an explicit descriptor played through DS. So, we are trying to phase out these code paths in DS. This has the added benefit of providing a more positive/declarative workflow; easier to reason what's going on.

A note about historyStateInfo play option: See SpacesExtension.js for more details. This play option is used to explicitly combine several play commands into one single history state. Example:

options = {
                historyStateInfo: {
                    name: strings.ACTIONS.APPLY_TEXT_STYLE,
                    target: documentLib.referenceBy.id(currentDocument.id)
                }
            };