An Atomic Package

/// The `.ariandel` document package.
///
/// ```
/// <id>.ariandel/
///   Artwork.json            manifest: canvas, background, layer stack, properties
///   Layers/<layer-id>.tiles every tile in the engine's native format, LZFSE-compressed
///   Layers/<mask-id>.tiles  a layer mask's paint, the same way
///   Selections/<id>.selection a saved selection's coverage, LZFSE-compressed
///   Preview.png             the flattened picture (projection, regenerable)
///   Thumbnail.png           small flattened picture for the gallery (projection)
/// ```
///
/// Tiles are stored losslessly in libmypaint's own format, so a reopened
/// artwork is bit-identical. PNG files are projections for galleries and
/// Quick Look; nothing reads pixels back from them.
public enum ArtworkFile {
    // ...

    /// Writes the package atomically: everything goes into a sibling temporary
    /// package first, which then replaces `url` in one step.
    public static func write(_ archive: ArtworkArchive, preview: Data? = nil, thumbnail: Data? = nil, to url: URL) throws {
        let manager = FileManager.default
        let parent = url.deletingLastPathComponent()
        try manager.createDirectory(at: parent, withIntermediateDirectories: true)
        let staging = parent.appendingPathComponent(".\(url.lastPathComponent).\(UUID().uuidString).saving",
                                                    isDirectory: true)
        try manager.createDirectory(at: staging.appendingPathComponent(layersDirectory), withIntermediateDirectories: true)
        do {
            // ... every layer, mask and saved selection, then Artwork.json,
            // Preview.png and Thumbnail.png, all written into staging ...
            if manager.fileExists(atPath: url.path) {
                _ = try manager.replaceItemAt(url, withItemAt: staging)
            } else {
                try manager.moveItem(at: staging, to: url)
            }
        } catch {
            try? manager.removeItem(at: staging)
            throw error
        }
    }

    /// `ARDT`, version, count, then per tile: x, y, flags (bit 0 = LZFSE), length, payload.
    /// All integers little-endian.
    static func encodeTiles(_ tiles: [(key: TileKey, tile: FrozenTile)]) throws -> Data {
        var out = Data(tileMagic)
        out.appendLittleEndian(UInt32(1))
        out.appendLittleEndian(UInt32(tiles.count))
        for (key, tile) in tiles {
            let bytes = tile.buffer.data
            let compressed = try (bytes as NSData).compressed(using: .lzfse) as Data
            let useCompressed = compressed.count < bytes.count
            out.appendLittleEndian(key.x)
            out.appendLittleEndian(key.y)
            out.appendLittleEndian(UInt32(useCompressed ? 1 : 0))
            let payload = useCompressed ? compressed : bytes
            out.appendLittleEndian(UInt32(payload.count))
            out.append(payload)
        }
        return out
    }

// A minimal sketch of an atomic package save in the shape of ArtworkFile.write:
// stage the whole package beside the target, then swap it in with one call.
// Build and run: swiftc -swift-version 6 package.swift -o package && ./package
import Foundation

struct Fail: Error {}

func writePackage(layers: [String: Data], to url: URL, failAfter: Int? = nil) throws {
    let manager = FileManager.default
    let parent = url.deletingLastPathComponent()
    let staging = parent.appendingPathComponent(".\(url.lastPathComponent).\(UUID().uuidString).saving",
                                                isDirectory: true)
    try manager.createDirectory(at: staging.appendingPathComponent("Layers"), withIntermediateDirectories: true)
    do {
        var written = 0
        for (id, raw) in layers.sorted(by: { $0.key < $1.key }) {
            if let failAfter, written == failAfter { throw Fail() }      // a crash, simulated
            // LZFSE only when it actually shrinks the bytes; flag says which.
            let packed = try (raw as NSData).compressed(using: .lzfse) as Data
            let useCompressed = packed.count < raw.count
            var file = Data([useCompressed ? 1 : 0])
            file.append(useCompressed ? packed : raw)
            try file.write(to: staging.appendingPathComponent("Layers/\(id).tiles"))
            written += 1
        }
        try Data(#"{"formatVersion":1}"#.utf8).write(to: staging.appendingPathComponent("Artwork.json"))
        if manager.fileExists(atPath: url.path) {
            _ = try manager.replaceItemAt(url, withItemAt: staging)
        } else {
            try manager.moveItem(at: staging, to: url)
        }
    } catch {
        try? manager.removeItem(at: staging)      // the old package was never touched
        throw error
    }
}

func listing(_ dir: URL) -> [String] {
    (try? FileManager.default.subpathsOfDirectory(atPath: dir.path).sorted()) ?? []
}

let root = FileManager.default.temporaryDirectory.appendingPathComponent("atomic-\(UUID().uuidString)")
try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
let url = root.appendingPathComponent("study.ariandel", isDirectory: true)

let flat = Data(repeating: 0x40, count: 32_768)                         // compresses well
let noise = Data((0..<32_768).map { _ in UInt8.random(in: 0...255) })  // does not
try writePackage(layers: ["A": flat, "B": noise, "C": flat], to: url)
print("first save:", listing(url))
for name in ["A", "B"] {
    let file = try Data(contentsOf: url.appendingPathComponent("Layers/\(name).tiles"))
    print("  \(name).tiles flag \(file[0]), \(file.count) bytes")
}

// Second save drops layer C and dies after one layer file.
do { try writePackage(layers: ["A": flat, "B": flat], to: url, failAfter: 1) } catch { print("second save failed") }
print("after the failure:", listing(url))
print("leftovers beside it:", listing(root).filter { $0.hasSuffix(".saving") })

// Third save succeeds: layer C's file is gone because the package was replaced whole.
try writePackage(layers: ["A": flat, "B": flat], to: url)
print("third save:", listing(url))

// App/AriandelApp.swift: leaving the foreground
        .onChange(of: scenePhase) { _, phase in
            if phase != .active {
                studio.saveOpenArtwork(reason: .leavingForeground)
            }
        }

// Canvas/CanvasModel.swift: every change but a selection-only one restarts the countdown
        if !change.isSubset(of: [.selection, .selectedArea]) {
            scheduleAutosave()
            timelapse?.noteChange()
            generationModel?.noteChange()
        }

    private func scheduleAutosave() {
        autosaveTask?.cancel()
        autosaveTask = Task { [weak self] in
            try? await Task.sleep(for: .seconds(4))
            guard !Task.isCancelled else { return }
            self?.save(reason: .autosave)
        }
    }

// Library/ArtworkLibrary.swift: one writer
/// Serializes package writes so two saves never interleave on disk.
actor ArtworkWriter {
    func write(_ archive: ArtworkArchive, preview: Data?, thumbnail: Data?, to url: URL) throws {
        try ArtworkFile.write(archive, preview: preview, thumbnail: thumbnail, to: url)
    }
}