The application operates using Regimes, which define the current state of the application and control which actions and UI elements are available, particularly on the Viewer page.

The regimes and their states are managed within RegimeProvider.ts. The Viewer component primarily reacts to these states. The existing regimes are: idling, staging, restoring, and viewing.

• This is the empty, initial default state of the application.
• When the viewer is cleared (e.g., via a "Clear Viewer" action), the application returns to the idling regime.
• In this state, all advanced functionalities (such as exporting data or creating views) are hidden or disabled.

• This regime acts as an intermediate bridge between external pages (like the Home page) and the Viewer page.
• The concept here is that a file has been loaded into memory, but the Viewer component itself must take responsibility for rendering it.
• To achieve this, the Viewer component utilizes a useEffect hook that listens for the staging regime. Once triggered, it begins processing the data and preparing it for display.

• This is the primary active state. The useEffect mentioned in the staging regime loads the file into the viewer, extracts the necessary views, and saves the state tree and source URL into the regime context.
• It also handles deconstructed assets, saving them as FileData objects with relative paths.
• Once this processing is complete, the application automatically switches to the viewing regime. Most editor operations and user interactions are available and defined within this state.

• If the user navigates away from the Viewer page while in the viewing state, the application must store the current workspace to allow for a seamless return.
• The restoring regime contains all the attributes of the viewing regime, but packs additional session-dependent data (like plugin snapshots).
• When the Viewer and Molstar are initialized, the system first checks if the current regime is restoring. If so, it passes the saved session data to the initMolstar function to reconstruct the workspace.
• Once restored, a dedicated useEffect sets the views and transitions the application back to the viewing regime.

The useFileManagement.tsx hooks are designed to handle loading and deconstructing files (transitioning the application from any state to staging, and then to viewing). When using the useRegime hook, you will typically only need to read the regime property to check the current state. The Viewer component manages the specialized restoring procedure internally.

Background data processing operates independently of the UI Regimes. Data processing is managed entirely by the ProcessingProvider.tsx. To trigger these processes, you typically use hooks from useFileManagement.tsx, such as the handleFile method.

This architectural separation allows users to continue interacting with the application (e.g., in the viewing regime) while heavy tasks run in the background.

Here is the step-by-step lifecycle of processing a file and moving it into the viewer:

1. Initiation: The user selects a file (e.g., a .map file). The current UI regime might be set to idling.
2. API Call: The handleFile method is invoked. This triggers an API call to a server-side procedure to begin processing the file.
3. Asset Generation: Upon successful processing, the server returns an array containing the absolute file paths of the newly created local assets.
4. MVS Index Creation: The client proceeds to create a default multiple MVS structure. This includes an index file (.mvsj) that utilizes relative paths to reference the newly created assets. (Note: These relative paths can be customized in the Settings, e.g., changing from ./ to ./volumes/).
5. Bundling: The index file and local assets are bundled into a .mvsx archive and exported to a temporary directory. This design supports future functionality, allowing users to choose whether to use local files or external URLs for each snapshot.
6. Transition to Staging: The UI regime is updated to staging, and a FileData object containing the bundled MVS data is passed into the context.
7. Deconstruction & Viewing: The useEffect inside Viewer.tsx detects the staging regime. It loads the bundled data into the viewer, extracts the views, and unpacks the local assets as a FileData array alongside the state tree and source URL. Finally, the regime is switched to viewing, populating the state with all extracted data.
8. Immediate Export (Optional): If the user decides to export the data immediately without making any changes in the viewer, the system can efficiently reuse the saved temporary archive.
9. Session Cleanup: At the end of the session, the temporary local archive and extracted assets are cleared to free up space.