Saving Sessions and Recovery

Saving Sessions and Recovery

This page explains permanent saves, automatic session restoration, and the safeguards ChemDraft 1.0.0 uses when a save or restore cannot safely proceed.

ChemDraft separates two related jobs. A save writes a file you choose and can keep outside the app. A session autosave records the current working state so the next launch can restore open tabs and unsaved changes. Use both: save deliberately named work as .chemdraft, and let session restoration protect the work in progress between launches.

Save your editable source

Use File > Save to write the current document. If it does not yet have a location, ChemDraft opens the native save picker. Use File > Save As… to choose a new location or make a separate version. Saved documents use the .chemdraft extension; if an entered filename does not end in .chemdraft or .cdxml, the app adds .chemdraft.

The native save is an editable, versioned ChemDraft document in a CDXML envelope. It includes the native document payload as well as the visible compatible layer. See File Formats and Compatibility for what that means and CDXML Support for interchange limits.

Saving changes the file association only after the write succeeds. If a save is cancelled or fails, the tab stays open and its drawing is retained. A failed save is not treated as a completed save.

What the session autosave retains

The working session is stored as document-session.json in the app-data directory. It is an internal recovery file, not a format to edit or share. ChemDraft writes it after an 800 ms debounce when document or file state changes, and also flushes it as part of the controlled close/quit flow.

The session records:

• every open tab and the active tab;
• each tab's serialized document, saved-file association, dirty state, and display name;
• whether a document was blank or pristine;
• the saved viewport and scroll position where available;
• open-time compatibility warnings; and
• recovery envelopes that could not be restored.

On restart, ChemDraft restores the tabs and active-tab position, including unsaved edits. It also understands the older single-document session shape. A fresh, pristine, empty one-tab canvas is intentionally not announced as a restored session, but a blank file, a changed blank canvas, multiple tabs, and recoverable retained tabs are restored.

Closing, quitting, and optional prompts

ChemDraft flushes the session during normal quitting so a recent edit inside the autosave debounce interval is not lost. On Windows, closing the document window quits after that flush. On macOS, closing the document window hides it; the application remains available to reopen from the Dock.

There is an optional Ask to save before quitting preference. When enabled, it prompts only if one or more tabs are dirty. Choose Save to save every dirty tab, Don't Save to continue with the retained session state, or Cancel to return to the application. The prompt does not turn session restoration off: choosing not to make permanent file saves does not discard the autosaved working drawings.

If a dirty tab has no file association, choosing Save opens the normal save picker. If saving is cancelled or fails, quitting is cancelled so you can choose what to do next.

When a restored path cannot be reused

For safety, session restore does not blindly grant access to arbitrary remembered locations. It considers only recorded absolute paths for existing regular .chemdraft or .cdxml files. It refuses directories, missing files, symlink components, and platform-specific reparse points. This protects the restore path rather than silently writing somewhere unexpected.

If access to a restored path cannot be renewed, ChemDraft retains the drawing, dirty state, and displayed association but explains that Save cannot reuse that path. Choose File > Save As… and select a new location. A successful Save As replaces the association. The access check is repeated on the next launch rather than permanently storing the failure.

If restoration has a problem

ChemDraft validates the outer session and each saved tab independently. A readable session can therefore restore healthy tabs while keeping unreadable tab envelopes for later recovery rather than overwriting them with a blank document. If the outer session itself cannot be read, autosave is disabled for that run to avoid replacing the recovery data with a new empty session.

In practical terms:

1. If a restored drawing appears, immediately use File > Save As… to make an independent .chemdraft copy when it is important.
2. If the app says the last session could not be read, do not assume a new blank canvas has replaced it; autosave is held back for that run.
3. If a tab says its saved path is unavailable, use Save As instead of repeatedly trying Save.
4. If a permanent file was damaged or cannot be opened, keep the original unchanged and consult Troubleshooting with the exact warning message.

Session restoration is a guard against ordinary interruption, not a replacement for intentional versioned saves or an external backup strategy.

See also

• File Formats and Compatibility
• CDXML Support
• Documents, Pages, and Tabs
• Troubleshooting