# Editor Session Recovery

Blacksite stores restart metadata in the user state directory, separate from project assets and
source-controlled settings:

- `$XDG_STATE_HOME/blacksite-editor/session.ron`, or
- `~/.local/state/blacksite-editor/session.ron` when `XDG_STATE_HOME` is unset.

The file uses schema v1 and is written transactionally. It contains project and scene paths, dock
and hierarchy metadata, non-destructive panel visibility, finite viewport camera bookmarks, and a
clean-shutdown marker. It never contains scene contents, unsaved tool previews, environment values,
or credentials.

## Restart behavior

- **Clean shutdown:** after the guarded exit path saves all dirty scene tabs or receives explicit
  Discard confirmation, the last authored scene and non-destructive UI state are restored.
- **Abnormal shutdown:** the editor opens its normal safe scene and displays **Recover Editor
  Session**. **Resume Last Scene** opens only the previous authored scene. **Continue Safe** keeps
  the startup scene. The prompt blocks interaction with the safe scene until either choice is made.
  Modal tools and dirty preview state are never restored.
- Native window close, **File > Quit**, project switching, and programmatic editor exit use one
  non-blocking Save All / Discard / Cancel workflow. Cancel and failed saves keep the session open.
  Direct `AppExit`, process kill, and crashes are not recorded as clean shutdowns.
- Dirty scene data remains governed by the independent scene recovery workflow in
  [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
- Dirty Materials, Material Instances, import settings, and project content defaults receive
  editor-local recovery snapshots after two seconds of inactivity. Five generations are retained
  outside project `assets/`. Startup restoration never overwrites source: a changed fingerprint
  restores the document as a conflict. Returning the document exactly to its source value clears
  older recovery generations; startup defensively ignores any recovery value that already matches
  source. See
  [ADR 0047](../adr/0047-editor-authored-asset-documents.md).

An unknown newer session schema is ignored safely. Legacy unversioned session documents migrate to
v1 after finite camera bookmark validation.

## Diagnostic bundles

**Window → Diagnostics → Export Diagnostic Bundle** writes a timestamped RON report under
`$XDG_STATE_HOME/blacksite-editor/diagnostics` or
`~/.local/state/blacksite-editor/diagnostics`. The write uses the same transactional replace
primitive as session and scene recovery data.

The v1 report allowlists editor and Bevy versions, target OS/architecture and build profile,
renderer adapter/backend/driver identity, project and active-scene paths, dirty flags, aggregate
level/brush validation counts, the prior-abnormal-shutdown flag, and up to 32 bounded Scene I/O
events. It excludes ECS and scene payloads, asset contents, environment values, host/user identity,
credentials, access tokens, camera transforms, and modal operator state. Review the plain-text RON
file before sharing it when project paths are sensitive.