beffroi-tools/docs/interfaces/midra-layout-recovery.md

39 lines
2.3 KiB
Markdown

# Midra Layout recovery, version 1
`last_project.json` lives beside the per-user `settings.json` (see
[settings paths](midra-layout-settings.md)). It is an internal UTF-8 JSON envelope,
not a named project export. Headless/default editors never access this path.
| Field | Meaning |
| --- | --- |
| `version` | Integer `1`; other versions rejected |
| `project` | Complete [project v9](midra-layout.md), including embedded reference bytes; its units, precision and validation apply without display rounding |
| `project_path` | Last opened/successfully saved named JSON path, or null; SVG exports do not change it |
| `manual_saved_at` | Unix UTC seconds of the last successful explicit project save, or null when unknown; recovery and measurement-point autosaves do not update it |
Unknown envelope fields and files over 100 MiB are rejected. Project validation
and reference decoding must succeed before replacing the editor. No file at
`project_path` is opened during recovery; it identifies the target for subsequent
measurement-point autosaves. The startup device connection remains governed by
application settings, not recovery.
Checkpoints run at most every two seconds, outside active pointer/resize gestures,
and on normal exit. Identical snapshots are skipped. Writes use the existing
same-directory temporary-file, file-sync and atomic replacement helper. A failed
write leaves the previous file intact and pauses retries until requested. Invalid
startup recovery is preserved; Retry reloads it, while explicitly starting New
project permits replacement. Multiple app instances share this single slot;
last successful writer wins.
Recovery retains applied values only: no undo history, pending text/format/import
drafts, transient tools, or credentials. A normal exit cancels unfinished canvas
gestures before the final checkpoint. The schema does not replace named project
JSON: Save continues to emit a bare project v9 document. Opening/New replaces the
single recovery slot; New warns with the manual-save age and Save/Discard/Cancel.
A failed or cancelled manual save never completes Save-and-create-new.
[Complete recovery example](midra-layout-recovery-v1.example.json) is exercised by the startup regression test.
Future breaking envelope changes require a version bump and explicit migration
or rejection. Recovery is not an interchange format; use Save for portable files.