[editor] add YAML file conflict detection for concurrent edits

[marnovdm]

So after opening a feature request for this (https://github.com/orgs/esphome/discussions/3456) I thought about it some more and figured it would be a good way to test Claude Code, which I'm currently testing for work. Using the awesome https://github.com/obra/superpowers this was pretty easy to do. I've reviewed everything manually and tested it and think it works well. I've years of experience doing Linux/DevOps and some fullstack development with Python as well, but I'm by no means a professional software developer so I'm open to any and all feedback. Claude described the PR below.

Screenshot

Summary

Implements client-side conflict detection for the ESPHome dashboard's YAML editor to prevent data loss when the same file is edited simultaneously in multiple browser tabs or by external editors.

Problem Solved:
When users edit a YAML configuration file in multiple browser tabs or with external editors, changes can silently overwrite each other, causing data loss. This PR adds conflict detection and resolution UI to handle these scenarios gracefully.

Changes

Modified Files

• src/api/files.ts - API layer with mtime-aware functions
• src/editor/esphome-editor.ts - Editor component with conflict detection

Implementation Details

API Layer (src/api/files.ts):

New exports:

• FileWithMtime interface: Type for mtime-aware file responses
• getFileWithMtime(): Fetches file content + X-File-Mtime header
• writeFileWithMtime(): Sends mtime parameter, detects 409 conflicts

Refactored:

• getFile(): Now uses getFileWithMtime() internally (backward compatible)
• writeFile(): Now uses writeFileWithMtime() internally (backward compatible)

Editor Component (src/editor/esphome-editor.ts):

State:

• fileMtime: string | null: Tracks current file's modification time

File Loading:

• Uses getFileWithMtime() to fetch content and mtime
• Stores mtime for later validation
• Preserves pre-existing secrets.yaml template behavior (mtime set to null for non-existent file)

Save Logic:

• Sends stored mtime to backend unless force override
• Handles 409 Conflict response → Shows dialog
• Handles 404 File Deleted response → Shows error
• Updates stored mtime after successful save

Conflict Resolution UI:

• Material Web Components dialog with clear messaging
• Two options:
  • Cancel: Close dialog, keep editor open for reference
  • Overwrite: Force save, bypassing conflict check
• Styled with theme's --alert-error-color for destructive action

User Experience

Normal Save (No Conflict)

User edits file → Clicks Save
                 → ✅ Success snackbar appears
                 → Editor continues normally

Conflict Detected

User opens file in Tab A → Loads with mtime: 1735419016.123
User opens file in Tab B → Loads with mtime: 1735419016.123

Tab A: Edit & Save → Success, new mtime: 1735419020.456
Tab B: Edit & Save → 409 Conflict detected
                    → Dialog appears:

                      Conflict Detected

                      This file was modified from another
                      tab or external editor.

                      Your options:
                      • Cancel - Don't save, editor remains
                        open for reference
                      • Overwrite - Save anyway, overwriting
                        changes on the server

                      [Cancel] [Overwrite]

User clicks "Cancel" → Dialog closes, editor open for reference
               OR
User clicks "Overwrite" → Force save, Tab A's changes lost

External Editor Conflict

User opens file in browser → Loads with mtime
User edits with vim/VS Code → File modified externally
User saves in browser → Conflict detected
                       → Dialog appears with options

Technical Details

Data Flow

File Load:

getFileWithMtime(filename)
  → GET /edit?configuration=filename
  ← 200 OK, X-File-Mtime: "1735419016.123"
  → Store in this.fileMtime

File Save (Normal):

writeFileWithMtime(filename, content, mtime)
  → POST /edit?configuration=filename&mtime=1735419016.123
  ← 200 OK, X-File-Mtime: "1735419020.456"
  → Update this.fileMtime with new value

File Save (Conflict):

writeFileWithMtime(filename, content, mtime)
  → POST /edit?configuration=filename&mtime=1735419016.123
  ← 409 Conflict, {"error": "File was modified..."}
  → Show conflict dialog

Force Save (Overwrite):

writeFileWithMtime(filename, content, undefined)
  → POST /edit?configuration=filename (no mtime param)
  ← 200 OK, X-File-Mtime: "1735419025.789"
  → Success (bypassed validation)

Note on Force Override:
The frontend achieves force override by omitting the mtime parameter entirely, rather than sending a force=true query parameter. This approach ensures zero version coupling between frontend and backend:

• Old backend without conflict detection → Works normally
• New backend with conflict detection → No mtime = skip validation

The backend implements a force parameter for potential future use (e.g., when implementing a diff viewer where we want to differentiate "no mtime available" vs "user explicitly chose to force override after seeing the diff"). This design allows future enhancements without breaking backward compatibility.

Error Handling

Status Code	Handler	User Feedback
200 OK	Update mtime, show success	"✅ Saved filename.yaml"
404 Not Found	Show error snackbar	"❌ File filename.yaml was deleted"
409 Conflict	Show conflict dialog	Dialog with Cancel/Overwrite
Other errors	Log and show generic error	"❌ An error occurred saving..."

Edge Cases Handled

1. New files: No mtime sent (files don't exist yet)
2. Force override: Omits mtime parameter instead of sending force=true (zero version coupling)
3. Save method parameter: Event object vs boolean discrimination in _saveFile(forceOrEvent)
4. Null mtime: Converted to undefined for optional parameter
5. Dialog closure: Explicit close() calls for Material Web Components
6. Pre-existing secrets.yaml behavior: Preserves existing template logic (sets mtime to null when file doesn't exist)

Backward Compatibility

✅ Fully backward compatible:

• All existing code using getFile() / writeFile() works unchanged
• Gracefully handles backends without mtime support (no errors, no validation)
• No breaking API changes
• Uses existing Material Web Components (no new dependencies)

Testing

Manual Testing Scenarios

Test 1: Multi-tab conflict

1. Open device.yaml in two tabs
2. Edit and save in Tab A → Success
3. Edit and save in Tab B → Conflict dialog appears
4. Click "Cancel" → Dialog closes, Tab B editor still open
5. Click "Overwrite" → Tab B's changes saved, Tab A now stale

Test 2: External editor

1. Open device.yaml in browser
2. Edit same file with vim/VS Code
3. Save in external editor
4. Save in browser → Conflict detected

Test 3: Sequential edits (no conflict)

1. Open file, edit, save → Success
2. Close tab
3. Open file again, edit, save → Success (fresh mtime)

Test 4: New file

1. Create new device via wizard
2. Open immediately, edit, save → Success (no mtime)

Test 5: secrets.yaml (existing file)

1. Open secrets.yaml → Works normally with mtime tracking
2. Edit and save → Conflict detection works normally
3. Edit in two tabs → Conflicts detected as expected

Test 6: secrets.yaml (non-existent)

1. Delete secrets.yaml if it exists
2. Open secrets.yaml → Template shown (pre-existing behavior)
3. Edit and save → Creates file with mtime
4. Further edits → Conflict detection works normally

UI/UX Considerations

Dialog Design Decisions:

• Cancel button: Primary action (safer default)
• Overwrite button: Secondary action with --alert-error-color (danger)
• No diff preview: Kept simple (YAGNI principle)
• Clear messaging: Explains consequences of each action
• Inline buttons: Uses Material Web Components' slot system

Alternative Considered:

• "Discard & Reload" option was considered but deemed unnecessary
• "Cancel" provides same safety while keeping local copy for reference

Integration

Requires backend PR:
This frontend PR must be deployed alongside the companion backend PR that:

• Returns X-File-Mtime headers
• Accepts mtime query parameters
• Returns 409 status on conflicts

Can be deployed independently:
Yes - gracefully degrades with old backend (no validation, but no errors).

Performance Impact

• Negligible: One additional header extraction per file load
• No extra requests: mtime sent as query parameter
• Memory overhead: One string property per editor instance

Related PRs

• ESPHome Backend PR: [dashboard] add YAML file conflict detection for concurrent edits esphome#12708
  • Implements server-side mtime validation
  • Returns 409 status on conflicts
  • Provides X-File-Mtime headers

Checklist

• Code follows project style guidelines
• TypeScript compiles with no errors
• No breaking changes introduced
• Backward compatible with existing code
• Uses existing theme colors (--alert-error-color)
• Material Web Components used correctly
• Error handling for all failure modes
• Manual testing completed
• Ready for review