diff --git a/src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs b/src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs
new file mode 100644
index 00000000..3c9e403e
--- /dev/null
+++ b/src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs
@@ -0,0 +1,64 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.IO;
+using Titano.Core.Metadata;
+
+namespace Titano.Core.Imaging.Thumbnails;
+
+/// Proxy long-edge policy (BRIEF §8.5).
+public enum ProxySize
+{
+ /// Source resolution.
+ Full = 0,
+ Edge1280 = 1280,
+ Edge1920 = 1920,
+ Edge2560 = 2560,
+}
+
+/// A built proxy and how its pixels were obtained.
+/// JPEG file bytes with an Exif block.
+/// Proxy width (oriented).
+/// Proxy height (oriented).
+/// Decode tier of the source (an embedded preview caps the proxy at the preview's size).
+public sealed record ProxyResult(byte[] Jpeg, int Width, int Height, DecodeTier Tier);
+
+///
+/// Builds proxies (BRIEF §8.5): the source decoded at the policy long edge (1280/1920/2560 or full) with its orientation
+/// applied, encoded as JPEG q92, carrying an Exif block written by from the
+/// source metadata (capture time, camera, exposure, GPS) with orientation reset to 1 because the pixels are upright.
+///
+public static class ProxyBuilder
+{
+ public const int Quality = 92;
+
+ /// Default policy.
+ public const ProxySize DefaultSize = ProxySize.Edge1920;
+
+ /// Decodes and encodes the proxy of ; null when no tier can decode it.
+ /// Source metadata; read from the file when null.
+ public static ProxyResult? Build(ImageDecoder decoder, string sourcePath, ProxySize size = DefaultSize, FrameMetadata? metadata = null, CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(decoder);
+ using var decoded = decoder.Decode(new DecodeRequest(sourcePath, (int)size, DecodePurpose.Proxy), cancellationToken);
+ if (decoded is null) return null;
+ metadata ??= MetadataReader.Read(sourcePath, cancellationToken);
+ return new ProxyResult(Encode(decoded.Pixels, metadata), decoded.Pixels.Width, decoded.Pixels.Height, decoded.Tier);
+ }
+
+ /// Builds the proxy and writes it crash-safely to .
+ public static ProxyResult? Write(ImageDecoder decoder, string sourcePath, string proxyPath, ProxySize size = DefaultSize, FrameMetadata? metadata = null, CancellationToken cancellationToken = default)
+ {
+ var result = Build(decoder, sourcePath, size, metadata, cancellationToken);
+ if (result is not null) AtomicFile.WriteAllBytes(proxyPath, result.Jpeg);
+ return result;
+ }
+
+ /// Encodes upright linear-light pixels as a proxy JPEG with the source's Exif (orientation 1).
+ public static byte[] Encode(ImageBuffer image, FrameMetadata metadata)
+ {
+ ArgumentNullException.ThrowIfNull(image);
+ ArgumentNullException.ThrowIfNull(metadata);
+ var segment = ExifWriter.BuildJpegApp1(metadata with { Orientation = 1, Width = image.Width, Height = image.Height });
+ // The encoder takes APP1 payloads: drop the marker and length that BuildJpegApp1 puts in front.
+ return JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = Quality, App1Segments = [segment[4..]], OptimizeHuffman = true });
+ }
+}
diff --git a/src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs b/src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs
new file mode 100644
index 00000000..863a4bba
--- /dev/null
+++ b/src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs
@@ -0,0 +1,156 @@
+using Titano.Core.Codecs.Jpeg;
+
+namespace Titano.Core.Imaging.Thumbnails;
+
+/// A decoded thumbnail ready for display: interleaved 8-bit sRGB RGB.
+public sealed class Thumbnail(int width, int height, byte[] rgb)
+{
+ public int Width { get; } = width;
+ public int Height { get; } = height;
+
+ /// Width × height × 3 bytes, sRGB-encoded, top-down.
+ public byte[] Rgb { get; } = rgb;
+
+ /// Memory charged against a budget.
+ public long ByteSize => Rgb.Length + 64;
+
+ /// Decodes a thumbnail JPEG (gray is expanded to RGB).
+ /// The JPEG is malformed.
+ public static Thumbnail FromJpeg(ReadOnlySpan jpeg)
+ {
+ var image = JpegDecoder.Decode(jpeg);
+ var pixels = image.Pixels8 ?? throw new InvalidDataException("Thumbnail: not an 8-bit JPEG");
+ if (image.Components == 3) return new Thumbnail(image.Width, image.Height, pixels);
+ var rgb = new byte[pixels.Length * 3];
+ for (var i = 0; i < pixels.Length; i++) rgb[3 * i] = rgb[3 * i + 1] = rgb[3 * i + 2] = pixels[i];
+ return new Thumbnail(image.Width, image.Height, rgb);
+ }
+}
+
+///
+/// In-memory LRU of decoded thumbnails under a byte budget (BRIEF §8.5). Thread-safe; concurrent requests for the same
+/// key share one load (), so a scrolling UI never decodes a thumbnail twice.
+///
+public sealed class ThumbnailCache where TKey : notnull
+{
+ private readonly Lock _gate = new();
+ private readonly Dictionary> _map = [];
+ private readonly LinkedList<(TKey Key, Thumbnail Value)> _lru = new();
+ private readonly Dictionary> _loading = [];
+ private long _bytes;
+
+ /// Upper bound on the bytes held (a thumbnail larger than the budget is never cached).
+ public ThumbnailCache(long byteBudget)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(byteBudget);
+ Budget = byteBudget;
+ }
+
+ public long Budget { get; }
+
+ public long Bytes
+ {
+ get
+ {
+ lock (_gate) return _bytes;
+ }
+ }
+
+ public int Count
+ {
+ get
+ {
+ lock (_gate) return _map.Count;
+ }
+ }
+
+ /// Returns a cached thumbnail and marks it most recently used.
+ public bool TryGet(TKey key, out Thumbnail thumbnail)
+ {
+ lock (_gate)
+ {
+ if (_map.TryGetValue(key, out var node))
+ {
+ _lru.Remove(node);
+ _lru.AddFirst(node);
+ thumbnail = node.Value.Value;
+ return true;
+ }
+ }
+ thumbnail = null!;
+ return false;
+ }
+
+ /// Adds or replaces a thumbnail, evicting least recently used ones to stay within the budget.
+ public void Set(TKey key, Thumbnail thumbnail)
+ {
+ ArgumentNullException.ThrowIfNull(thumbnail);
+ lock (_gate)
+ {
+ RemoveLocked(key);
+ if (thumbnail.ByteSize > Budget) return;
+ _map[key] = _lru.AddFirst((key, thumbnail));
+ _bytes += thumbnail.ByteSize;
+ while (_bytes > Budget && _lru.Last is { } last)
+ {
+ RemoveLocked(last.Value.Key);
+ }
+ }
+ }
+
+ public bool Remove(TKey key)
+ {
+ lock (_gate) return RemoveLocked(key);
+ }
+
+ public void Clear()
+ {
+ lock (_gate)
+ {
+ _map.Clear();
+ _lru.Clear();
+ _bytes = 0;
+ }
+ }
+
+ /// Cached thumbnail, or the result of (cached when not null). Concurrent calls for
+ /// the same key await the same load; each caller's only cancels its own wait.
+ public async Task GetOrLoadAsync(TKey key, Func> loader, CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(loader);
+ if (TryGet(key, out var hit)) return hit;
+ Task task;
+ lock (_gate)
+ {
+ if (!_loading.TryGetValue(key, out task!))
+ {
+ task = LoadAsync(key, loader);
+ _loading[key] = task;
+ }
+ }
+ return await task.WaitAsync(cancellationToken).ConfigureAwait(false);
+ }
+
+ private async Task LoadAsync(TKey key, Func> loader)
+ {
+ try
+ {
+ await Task.Yield();
+ var value = await loader(key, CancellationToken.None).ConfigureAwait(false);
+ if (value is not null) Set(key, value);
+ return value;
+ }
+ finally
+ {
+ lock (_gate) _loading.Remove(key);
+ }
+ }
+
+ private bool RemoveLocked(TKey key)
+ {
+ if (!_map.Remove(key, out var node)) return false;
+ _lru.Remove(node);
+ _bytes -= node.Value.Value.ByteSize;
+ return true;
+ }
+}
diff --git a/src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs b/src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs
new file mode 100644
index 00000000..3d6e104d
--- /dev/null
+++ b/src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs
@@ -0,0 +1,497 @@
+using System.Buffers.Binary;
+using System.Collections.Concurrent;
+using Microsoft.Win32.SafeHandles;
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Hashing;
+using Titano.Core.IO;
+
+namespace Titano.Core.Imaging.Thumbnails;
+
+/// Index entry of one thumbnail in a .
+/// Frame the thumbnail belongs to.
+/// File offset of the entry record.
+/// JPEG length in bytes.
+/// Thumbnail width in pixels.
+/// Thumbnail height in pixels.
+/// CRC-32 of the JPEG bytes.
+public readonly record struct ThumbnailEntry(Guid FrameId, long Offset, int Length, int Width, int Height, uint Crc);
+
+///
+/// The per-sequence thumbnail file thumbs.pack (BRIEF §8.5): 320-pixel JPEG (q80) thumbnails appended to one file.
+/// Layout (little-endian): two 64-byte header slots at 0 and 64 (magic "TTPK", version, generation, offset/length/
+/// count of the current index record, the file length it covers, CRC-32); from 128, self-describing records — entries
+/// ("TENT": frame id, size, JPEG length and CRC, then the JPEG) and index tables ("TIDX": count, then frame id → offset,
+/// length, size, CRC per entry, then the record's CRC).
+/// Writes only append. Every appends (and on /)
+/// a new index record is appended and flushed, then the header slot not holding the newest generation is overwritten and
+/// flushed: a crash leaves the previous slot valid. Opening takes the newest valid slot, then recovers entries appended
+/// after its index by scanning forward until the first damaged record, so truncated or partially written files lose
+/// only their damaged tail. rewrites live entries into a fresh file committed with
+/// . Reads use positional I/O and run concurrently with one writer.
+///
+public sealed class ThumbnailPack : IDisposable
+{
+ public const int LongEdge = 320;
+ public const int Quality = 80;
+ public const int IndexInterval = 64;
+
+ private const uint HeaderMagic = 0x4B505454; // "TTPK"
+ private const uint EntryMagic = 0x544E4554; // "TENT"
+ private const uint IndexMagic = 0x58444954; // "TIDX"
+ private const ushort Version = 1;
+ private const int SlotSize = 64;
+ private const int DataStart = 2 * SlotSize;
+ private const int EntryHeaderSize = 32;
+ private const int IndexEntrySize = 36;
+ private const int MaxJpegBytes = 16 << 20;
+
+ private readonly ReaderWriterLockSlim _handleLock = new(LockRecursionPolicy.NoRecursion);
+ private readonly Lock _writeLock = new();
+ private readonly List _warnings = [];
+ private ConcurrentDictionary _index = new();
+ private SafeFileHandle _handle;
+ private long _tail;
+ private ulong _generation;
+ private int _activeSlot;
+ private int _unindexed;
+ private long _liveBytes;
+ private bool _disposed;
+
+ private ThumbnailPack(string path, bool writable, SafeFileHandle handle)
+ {
+ Path = path;
+ Writable = writable;
+ _handle = handle;
+ Load();
+ }
+
+ public string Path { get; }
+ public bool Writable { get; }
+
+ /// Problems met while opening or refreshing (damaged slots, records dropped from the tail).
+ public IReadOnlyList Warnings
+ {
+ get
+ {
+ lock (_warnings) return [.. _warnings];
+ }
+ }
+
+ public int Count => Volatile.Read(ref _index).Count;
+
+ /// Snapshot of the frames with a thumbnail.
+ public IReadOnlyCollection FrameIds => [.. Volatile.Read(ref _index).Keys];
+
+ /// Bytes held by superseded or removed entries (reclaimed by ).
+ public long WastedBytes => long.Max(0, _tail - DataStart - Volatile.Read(ref _liveBytes));
+
+ /// Opens (creating when writable and missing) a pack.
+ public static ThumbnailPack Open(string path, bool writable = true)
+ {
+ ArgumentException.ThrowIfNullOrEmpty(path);
+ if (writable && !File.Exists(path)) AtomicFile.WriteAllBytes(path, EmptyFile());
+ var handle = File.OpenHandle(path, FileMode.Open, writable ? FileAccess.ReadWrite : FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, FileOptions.RandomAccess);
+ return new ThumbnailPack(path, writable, handle);
+ }
+
+ /// Downscales a linear-light image to the thumbnail long edge and encodes it (JPEG q80).
+ public static (byte[] Jpeg, int Width, int Height) Encode(ImageBuffer image)
+ {
+ ArgumentNullException.ThrowIfNull(image);
+ using var small = Resampler.Thumbnail(image, LongEdge);
+ return (JpegEncoder.Encode(small, new JpegEncodeOptions { Quality = Quality }), small.Width, small.Height);
+ }
+
+ public bool TryGetEntry(Guid frameId, out ThumbnailEntry entry) => Volatile.Read(ref _index).TryGetValue(frameId, out entry);
+
+ /// The JPEG bytes of a frame's thumbnail; null when absent or damaged (CRC mismatch).
+ public byte[]? ReadJpeg(Guid frameId)
+ {
+ if (!TryGetEntry(frameId, out var e)) return null;
+ var data = new byte[e.Length];
+ _handleLock.EnterReadLock();
+ try
+ {
+ ObjectDisposedException.ThrowIf(_disposed, this);
+ if (RandomAccess.Read(_handle, data, e.Offset + EntryHeaderSize) != data.Length) return null;
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ return Crc32.Compute(data) == e.Crc ? data : null;
+ }
+
+ /// Encodes and appends the thumbnail of , replacing any previous one for the frame.
+ public ThumbnailEntry Add(Guid frameId, ImageBuffer image)
+ {
+ var (jpeg, w, h) = Encode(image);
+ return AddJpeg(frameId, jpeg, w, h);
+ }
+
+ /// Appends an encoded thumbnail, replacing any previous one for the frame.
+ public ThumbnailEntry AddJpeg(Guid frameId, ReadOnlySpan jpeg, int width, int height)
+ {
+ if (!Writable) throw new InvalidOperationException("The pack is open read-only.");
+ if (jpeg.Length is 0 or > MaxJpegBytes) throw new ArgumentOutOfRangeException(nameof(jpeg));
+ if (width is < 1 or > ushort.MaxValue || height is < 1 or > ushort.MaxValue) throw new ArgumentOutOfRangeException(nameof(width));
+ lock (_writeLock)
+ {
+ var record = new byte[EntryHeaderSize + jpeg.Length];
+ BinaryPrimitives.WriteUInt32LittleEndian(record, EntryMagic);
+ frameId.TryWriteBytes(record.AsSpan(4));
+ BinaryPrimitives.WriteUInt16LittleEndian(record.AsSpan(20), (ushort)width);
+ BinaryPrimitives.WriteUInt16LittleEndian(record.AsSpan(22), (ushort)height);
+ BinaryPrimitives.WriteInt32LittleEndian(record.AsSpan(24), jpeg.Length);
+ var crc = Crc32.Compute(jpeg);
+ BinaryPrimitives.WriteUInt32LittleEndian(record.AsSpan(28), crc);
+ jpeg.CopyTo(record.AsSpan(EntryHeaderSize));
+ var entry = new ThumbnailEntry(frameId, _tail, jpeg.Length, width, height, crc);
+ WriteAt(record, _tail);
+ _tail += record.Length;
+ if (_index.TryGetValue(frameId, out var old)) Interlocked.Add(ref _liveBytes, -(EntryHeaderSize + old.Length));
+ _index[frameId] = entry;
+ Interlocked.Add(ref _liveBytes, record.Length);
+ if (++_unindexed >= IndexInterval) WriteIndex();
+ return entry;
+ }
+ }
+
+ /// Drops a frame's thumbnail from the index (its bytes stay until ).
+ public bool Remove(Guid frameId)
+ {
+ if (!Writable) throw new InvalidOperationException("The pack is open read-only.");
+ lock (_writeLock)
+ {
+ if (!_index.TryRemove(frameId, out var old)) return false;
+ Interlocked.Add(ref _liveBytes, -(EntryHeaderSize + old.Length));
+ _unindexed++;
+ return true;
+ }
+ }
+
+ /// Writes the index now (appended record, then the alternate header slot).
+ public void Flush()
+ {
+ if (!Writable) return;
+ lock (_writeLock)
+ {
+ if (_unindexed > 0) WriteIndex();
+ }
+ }
+
+ /// Rewrites the live entries into a new file and atomically replaces this one.
+ public void Compact()
+ {
+ if (!Writable) throw new InvalidOperationException("The pack is open read-only.");
+ lock (_writeLock)
+ {
+ var temp = AtomicFile.TempPathFor(Path);
+ var entries = Volatile.Read(ref _index).Values.OrderBy(e => e.Offset).ToList();
+ var moved = new ConcurrentDictionary();
+ using (var output = new FileStream(temp, FileMode.CreateNew, FileAccess.Write, FileShare.None, 1 << 16))
+ {
+ output.Write(new byte[DataStart]);
+ var buffer = new byte[EntryHeaderSize + MaxJpegBytes / 16];
+ foreach (var e in entries)
+ {
+ var size = EntryHeaderSize + e.Length;
+ if (buffer.Length < size) buffer = new byte[size];
+ _handleLock.EnterReadLock();
+ int read;
+ try
+ {
+ read = RandomAccess.Read(_handle, buffer.AsSpan(0, size), e.Offset);
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ if (read != size || Crc32.Compute(buffer.AsSpan(EntryHeaderSize, e.Length)) != e.Crc)
+ {
+ Warn($"Thumbnail of {e.FrameId} damaged; dropped during compaction");
+ continue;
+ }
+ moved[e.FrameId] = e with { Offset = output.Position };
+ output.Write(buffer, 0, size);
+ }
+ var indexOffset = output.Position;
+ var index = IndexRecord(moved.Values);
+ output.Write(index);
+ output.Position = 0;
+ output.Write(HeaderSlot(_generation + 1, indexOffset, index.Length, moved.Count, indexOffset + index.Length));
+ }
+ _handleLock.EnterWriteLock();
+ try
+ {
+ _handle.Dispose();
+ AtomicFile.Commit(temp, Path);
+ _handle = File.OpenHandle(Path, FileMode.Open, FileAccess.ReadWrite, FileShare.ReadWrite | FileShare.Delete, FileOptions.RandomAccess);
+ _index = moved;
+ _generation++;
+ _activeSlot = 0;
+ _tail = RandomAccess.GetLength(_handle);
+ _liveBytes = moved.Values.Sum(e => (long)EntryHeaderSize + e.Length);
+ _unindexed = 0;
+ }
+ finally
+ {
+ _handleLock.ExitWriteLock();
+ }
+ }
+ }
+
+ /// Re-reads the file (read-only instances use it to see entries written by another instance).
+ public void Refresh()
+ {
+ if (Writable) return;
+ _handleLock.EnterWriteLock();
+ try
+ {
+ ObjectDisposedException.ThrowIf(_disposed, this);
+ _handle.Dispose();
+ _handle = File.OpenHandle(Path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, FileOptions.RandomAccess);
+ }
+ finally
+ {
+ _handleLock.ExitWriteLock();
+ }
+ Load();
+ }
+
+ public void Dispose()
+ {
+ if (_disposed) return;
+ if (Writable)
+ {
+ try
+ {
+ Flush();
+ }
+ catch (IOException ex)
+ {
+ Warn("Index not written on close: " + ex.Message);
+ }
+ }
+ _handleLock.EnterWriteLock();
+ try
+ {
+ _disposed = true;
+ _handle.Dispose();
+ }
+ finally
+ {
+ _handleLock.ExitWriteLock();
+ }
+ _handleLock.Dispose();
+ }
+
+ private static byte[] EmptyFile()
+ {
+ var file = new byte[DataStart];
+ HeaderSlot(1, 0, 0, 0, DataStart).CopyTo(file, 0);
+ return file;
+ }
+
+ private static byte[] HeaderSlot(ulong generation, long indexOffset, int indexLength, int count, long dataEnd)
+ {
+ var slot = new byte[SlotSize];
+ BinaryPrimitives.WriteUInt32LittleEndian(slot, HeaderMagic);
+ BinaryPrimitives.WriteUInt16LittleEndian(slot.AsSpan(4), Version);
+ BinaryPrimitives.WriteUInt64LittleEndian(slot.AsSpan(8), generation);
+ BinaryPrimitives.WriteInt64LittleEndian(slot.AsSpan(16), indexOffset);
+ BinaryPrimitives.WriteInt32LittleEndian(slot.AsSpan(24), indexLength);
+ BinaryPrimitives.WriteInt32LittleEndian(slot.AsSpan(28), count);
+ BinaryPrimitives.WriteInt64LittleEndian(slot.AsSpan(32), dataEnd);
+ BinaryPrimitives.WriteUInt32LittleEndian(slot.AsSpan(SlotSize - 4), Crc32.Compute(slot.AsSpan(0, SlotSize - 4)));
+ return slot;
+ }
+
+ private static byte[] IndexRecord(IEnumerable entries)
+ {
+ var list = entries.ToList();
+ var record = new byte[8 + list.Count * IndexEntrySize + 4];
+ BinaryPrimitives.WriteUInt32LittleEndian(record, IndexMagic);
+ BinaryPrimitives.WriteInt32LittleEndian(record.AsSpan(4), list.Count);
+ for (var i = 0; i < list.Count; i++)
+ {
+ var s = record.AsSpan(8 + i * IndexEntrySize, IndexEntrySize);
+ var e = list[i];
+ e.FrameId.TryWriteBytes(s);
+ BinaryPrimitives.WriteInt64LittleEndian(s[16..], e.Offset);
+ BinaryPrimitives.WriteInt32LittleEndian(s[24..], e.Length);
+ BinaryPrimitives.WriteUInt16LittleEndian(s[28..], (ushort)e.Width);
+ BinaryPrimitives.WriteUInt16LittleEndian(s[30..], (ushort)e.Height);
+ BinaryPrimitives.WriteUInt32LittleEndian(s[32..], e.Crc);
+ }
+ BinaryPrimitives.WriteUInt32LittleEndian(record.AsSpan(record.Length - 4), Crc32.Compute(record.AsSpan(0, record.Length - 4)));
+ return record;
+ }
+
+ /// Appends an index record, flushes, then commits it through the header slot not holding the newest generation.
+ private void WriteIndex()
+ {
+ var index = Volatile.Read(ref _index);
+ var record = IndexRecord(index.Values);
+ var offset = _tail;
+ WriteAt(record, offset);
+ _tail += record.Length;
+ RandomAccess.FlushToDisk(_handle);
+ var slot = 1 - _activeSlot;
+ WriteAt(HeaderSlot(_generation + 1, offset, record.Length, index.Count, _tail), slot * SlotSize);
+ RandomAccess.FlushToDisk(_handle);
+ _generation++;
+ _activeSlot = slot;
+ _unindexed = 0;
+ }
+
+ private void WriteAt(ReadOnlySpan data, long offset)
+ {
+ _handleLock.EnterReadLock();
+ try
+ {
+ ObjectDisposedException.ThrowIf(_disposed, this);
+ RandomAccess.Write(_handle, data, offset);
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ }
+
+ private void Warn(string message)
+ {
+ lock (_warnings)
+ {
+ if (_warnings.Count < 32) _warnings.Add(message);
+ }
+ }
+
+ /// Reads the newest valid header slot and its index, then recovers entries appended after it.
+ private void Load()
+ {
+ long length;
+ _handleLock.EnterReadLock();
+ try
+ {
+ length = RandomAccess.GetLength(_handle);
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ var index = new ConcurrentDictionary();
+ long scanFrom = DataStart;
+ (_generation, _activeSlot) = (0, 1);
+ var slots = new byte[DataStart];
+ var slotBytes = ReadAt(slots, 0);
+ for (var s = 0; s < 2; s++)
+ {
+ if (slotBytes < (s + 1) * SlotSize || ParseSlot(slots.AsSpan(s * SlotSize, SlotSize)) is not { } h)
+ {
+ if (slotBytes >= (s + 1) * SlotSize && slots.AsSpan(s * SlotSize, SlotSize).ContainsAnyExcept((byte)0)) Warn($"Header slot {s} damaged");
+ continue;
+ }
+ if (h.Generation <= _generation) continue;
+ var loaded = h.IndexLength > 0 ? ReadIndex(h.IndexOffset, h.IndexLength, length) : new ConcurrentDictionary();
+ if (loaded is null)
+ {
+ Warn($"Index of header slot {s} damaged");
+ continue;
+ }
+ (_generation, _activeSlot) = (h.Generation, s);
+ index = loaded;
+ scanFrom = h.DataEnd;
+ }
+ if (_generation == 0) Warn("No valid header; entries recovered by scanning");
+ _tail = length <= DataStart ? DataStart : Recover(index, long.Clamp(scanFrom, DataStart, length), length);
+ _index = index;
+ _liveBytes = index.Values.Sum(e => (long)EntryHeaderSize + e.Length);
+ _unindexed = 0;
+ }
+
+ private readonly record struct Slot(ulong Generation, long IndexOffset, int IndexLength, long DataEnd);
+
+ private static Slot? ParseSlot(ReadOnlySpan s)
+ {
+ if (BinaryPrimitives.ReadUInt32LittleEndian(s) != HeaderMagic || BinaryPrimitives.ReadUInt16LittleEndian(s[4..]) != Version) return null;
+ if (Crc32.Compute(s[..(SlotSize - 4)]) != BinaryPrimitives.ReadUInt32LittleEndian(s[(SlotSize - 4)..])) return null;
+ return new Slot(BinaryPrimitives.ReadUInt64LittleEndian(s[8..]), BinaryPrimitives.ReadInt64LittleEndian(s[16..]),
+ BinaryPrimitives.ReadInt32LittleEndian(s[24..]), BinaryPrimitives.ReadInt64LittleEndian(s[32..]));
+ }
+
+ private ConcurrentDictionary? ReadIndex(long offset, int length, long fileLength)
+ {
+ if (offset < DataStart || length < 12 || offset > fileLength - length || (length - 12) % IndexEntrySize != 0) return null;
+ var record = new byte[length];
+ if (ReadAt(record, offset) != length) return null;
+ if (BinaryPrimitives.ReadUInt32LittleEndian(record) != IndexMagic
+ || Crc32.Compute(record.AsSpan(0, length - 4)) != BinaryPrimitives.ReadUInt32LittleEndian(record.AsSpan(length - 4))) return null;
+ var count = BinaryPrimitives.ReadInt32LittleEndian(record.AsSpan(4));
+ if (count != (length - 12) / IndexEntrySize) return null;
+ var index = new ConcurrentDictionary();
+ for (var i = 0; i < count; i++)
+ {
+ var s = record.AsSpan(8 + i * IndexEntrySize, IndexEntrySize);
+ var e = new ThumbnailEntry(new Guid(s[..16]), BinaryPrimitives.ReadInt64LittleEndian(s[16..]), BinaryPrimitives.ReadInt32LittleEndian(s[24..]),
+ BinaryPrimitives.ReadUInt16LittleEndian(s[28..]), BinaryPrimitives.ReadUInt16LittleEndian(s[30..]), BinaryPrimitives.ReadUInt32LittleEndian(s[32..]));
+ if (e.Offset >= DataStart && e.Length is > 0 and <= MaxJpegBytes && e.Offset <= fileLength - EntryHeaderSize - e.Length) index[e.FrameId] = e;
+ }
+ return index;
+ }
+
+ /// Walks records from , adding valid entries (later ones win) and skipping index
+ /// records; stops at the first damaged or truncated record. Returns the end of the last good record.
+ private long Recover(ConcurrentDictionary index, long position, long length)
+ {
+ var head = new byte[EntryHeaderSize];
+ var recovered = 0;
+ while (position + 12 <= length)
+ {
+ var n = ReadAt(head.AsSpan(0, (int)long.Min(EntryHeaderSize, length - position)), position);
+ var magic = BinaryPrimitives.ReadUInt32LittleEndian(head);
+ if (magic == IndexMagic && n >= 8)
+ {
+ var count = BinaryPrimitives.ReadInt32LittleEndian(head.AsSpan(4));
+ var size = 12L + (long)count * IndexEntrySize;
+ if (count < 0 || position + size > length || ReadIndex(position, (int)long.Min(size, int.MaxValue), length) is null) break;
+ position += size;
+ continue;
+ }
+ if (magic != EntryMagic || n < EntryHeaderSize) break;
+ var jpegLength = BinaryPrimitives.ReadInt32LittleEndian(head.AsSpan(24));
+ if (jpegLength is <= 0 or > MaxJpegBytes || position + EntryHeaderSize + jpegLength > length) break;
+ var jpeg = new byte[jpegLength];
+ if (ReadAt(jpeg, position + EntryHeaderSize) != jpegLength) break;
+ var crc = BinaryPrimitives.ReadUInt32LittleEndian(head.AsSpan(28));
+ if (Crc32.Compute(jpeg) != crc) break;
+ var id = new Guid(head.AsSpan(4, 16));
+ index[id] = new ThumbnailEntry(id, position, jpegLength, BinaryPrimitives.ReadUInt16LittleEndian(head.AsSpan(20)), BinaryPrimitives.ReadUInt16LittleEndian(head.AsSpan(22)), crc);
+ position += EntryHeaderSize + jpegLength;
+ recovered++;
+ }
+ if (position < length) Warn($"Ignored {length - position} damaged bytes at the end of the pack");
+ if (recovered > 0) Warn($"Recovered {recovered} thumbnail(s) appended after the last index");
+ return position;
+ }
+
+ private int ReadAt(Span buffer, long offset)
+ {
+ _handleLock.EnterReadLock();
+ try
+ {
+ var total = 0;
+ while (total < buffer.Length)
+ {
+ var n = RandomAccess.Read(_handle, buffer[total..], offset + total);
+ if (n == 0) break;
+ total += n;
+ }
+ return total;
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ }
+}
diff --git a/tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs b/tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs
new file mode 100644
index 00000000..7690ef7c
--- /dev/null
+++ b/tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs
@@ -0,0 +1,277 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Decoders;
+using Titano.Core.Imaging.Thumbnails;
+using Titano.Core.Metadata;
+using Titano.Core.Model;
+using Titano.Core.Tests.Raw;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Decoding;
+
+/// format behaviour, and .
+public sealed class ThumbnailTests(TestContext context)
+{
+ private readonly string _dir = context.CreateTempDirectory();
+
+ private static ImageBuffer Frame(int seed, int width = 400, int height = 300)
+ {
+ var image = new ImageBuffer(width, height);
+ for (var y = 0; y < height; y++)
+ {
+ for (var x = 0; x < width; x++)
+ {
+ image[0, x, y] = (x + seed * 13) % 97 / 96f;
+ image[1, x, y] = (y + seed * 7) % 89 / 88f;
+ image[2, x, y] = seed % 5 / 5f;
+ }
+ }
+ return image;
+ }
+
+ /// Small distinct JPEGs (cheap to make in bulk).
+ private static byte[] Jpeg(int seed)
+ {
+ using var image = Frame(seed, 40, 30);
+ return JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = 80 });
+ }
+
+ private static Guid Id(int i) => new(i, 0, 0, [0, 0, 0, 0, 0, 0, 0, 1]);
+
+ [Test]
+ public void RoundTripAppendAndReplace()
+ {
+ var path = Path.Combine(_dir, "thumbs.pack");
+ using (var pack = ThumbnailPack.Open(path))
+ {
+ for (var i = 0; i < 20; i++)
+ {
+ using var frame = Frame(i);
+ var e = pack.Add(Id(i), frame);
+ Assert.Equal(320, e.Width);
+ Assert.Equal(240, e.Height);
+ }
+ }
+ using (var pack = ThumbnailPack.Open(path))
+ {
+ Assert.Equal(20, pack.Count);
+ Assert.Empty(pack.Warnings);
+ for (var i = 20; i < 25; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30);
+ pack.AddJpeg(Id(3), Jpeg(1000), 40, 30);
+ }
+ using var reader = ThumbnailPack.Open(path, writable: false);
+ Assert.Equal(25, reader.Count);
+ Assert.BytesEqual(Jpeg(1000), reader.ReadJpeg(Id(3)));
+ Assert.BytesEqual(Jpeg(22), reader.ReadJpeg(Id(22)));
+ var thumb = Thumbnail.FromJpeg(reader.ReadJpeg(Id(7))!);
+ Assert.Equal(320, thumb.Width);
+ Assert.Null(reader.ReadJpeg(Id(99)));
+ Assert.Greater(reader.WastedBytes, 0);
+ }
+
+ [Test]
+ public void EntriesAfterTheLastIndexAreRecovered()
+ {
+ var path = Path.Combine(_dir, "crash.pack");
+ var copy = Path.Combine(_dir, "crash-copy.pack");
+ var count = ThumbnailPack.IndexInterval + 6;
+ using (var pack = ThumbnailPack.Open(path))
+ {
+ for (var i = 0; i < count; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30);
+ // Simulated crash: the file as it is before the closing index write.
+ File.Copy(path, copy);
+ }
+ using var recovered = ThumbnailPack.Open(copy, writable: false);
+ Assert.Equal(count, recovered.Count);
+ Assert.Contains(recovered.Warnings, w => w.Contains("Recovered 6"));
+ Assert.BytesEqual(Jpeg(count - 1), recovered.ReadJpeg(Id(count - 1)));
+ }
+
+ [Test]
+ public void TruncatedAndDamagedFilesOpen()
+ {
+ var path = Path.Combine(_dir, "full.pack");
+ using (var pack = ThumbnailPack.Open(path))
+ {
+ for (var i = 0; i < 40; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30);
+ }
+ var bytes = File.ReadAllBytes(path);
+ for (var cut = 0; cut <= 40; cut++)
+ {
+ var file = Path.Combine(_dir, $"cut{cut}.pack");
+ File.WriteAllBytes(file, bytes[..(int)((long)bytes.Length * cut / 40)]);
+ using var pack = ThumbnailPack.Open(file, writable: false);
+ foreach (var id in pack.FrameIds) Assert.NotNull(pack.ReadJpeg(id));
+ Assert.LessOrEqual(pack.Count, 40);
+ }
+ // A damaged newest header slot falls back to the other one (or a scan).
+ var damaged = (byte[])bytes.Clone();
+ for (var i = 0; i < 128; i++) damaged[i] ^= 0x5A;
+ var damagedPath = Path.Combine(_dir, "damaged.pack");
+ File.WriteAllBytes(damagedPath, damaged);
+ using (var pack = ThumbnailPack.Open(damagedPath, writable: false))
+ {
+ Assert.Equal(40, pack.Count);
+ Assert.Contains(pack.Warnings, w => w.Contains("No valid header"));
+ }
+ // A flipped JPEG byte is caught by its CRC on read.
+ var flipped = (byte[])bytes.Clone();
+ flipped[128 + 40] ^= 0xFF;
+ var flippedPath = Path.Combine(_dir, "flipped.pack");
+ File.WriteAllBytes(flippedPath, flipped);
+ using var f = ThumbnailPack.Open(flippedPath, writable: false);
+ Assert.Null(f.ReadJpeg(Id(0)));
+ Assert.NotNull(f.ReadJpeg(Id(1)));
+ }
+
+ [Test]
+ public void CompactionDropsDeadEntries()
+ {
+ var path = Path.Combine(_dir, "compact.pack");
+ using var pack = ThumbnailPack.Open(path);
+ for (var i = 0; i < 30; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30);
+ for (var i = 0; i < 10; i++) pack.AddJpeg(Id(i), Jpeg(i + 500), 40, 30);
+ for (var i = 25; i < 30; i++) Assert.True(pack.Remove(Id(i)));
+ pack.Flush();
+ var before = new FileInfo(path).Length;
+ var wasted = pack.WastedBytes;
+ pack.Compact();
+ var after = new FileInfo(path).Length;
+ context.Log($"compaction {before} → {after} bytes (wasted {wasted})");
+ Assert.Less(after, before - wasted / 2);
+ Assert.Equal(25, pack.Count);
+ Assert.Null(pack.ReadJpeg(Id(27)));
+ Assert.BytesEqual(Jpeg(503), pack.ReadJpeg(Id(3)));
+ pack.AddJpeg(Id(100), Jpeg(100), 40, 30);
+ pack.Flush();
+ using var reopened = ThumbnailPack.Open(path, writable: false);
+ Assert.Equal(26, reopened.Count);
+ Assert.Empty(reopened.Warnings);
+ Assert.BytesEqual(Jpeg(15), reopened.ReadJpeg(Id(15)));
+ }
+
+ [Test]
+ [Timeout(20_000)]
+ public async Task ConcurrentReadsWhileWriting()
+ {
+ var path = Path.Combine(_dir, "concurrent.pack");
+ var jpegs = Enumerable.Range(0, 200).Select(Jpeg).ToArray();
+ using var pack = ThumbnailPack.Open(path);
+ for (var i = 0; i < 10; i++) pack.AddJpeg(Id(i), jpegs[i], 40, 30);
+ pack.Flush();
+ using var done = new CancellationTokenSource();
+ var writer = Task.Run(() =>
+ {
+ for (var i = 10; i < 200; i++) pack.AddJpeg(Id(i), jpegs[i], 40, 30);
+ pack.Flush();
+ done.Cancel();
+ });
+ var readers = Enumerable.Range(0, 4).Select(r => Task.Run(() =>
+ {
+ var random = new Random(r);
+ var reads = 0;
+ while (!done.IsCancellationRequested || reads < 50)
+ {
+ var ids = pack.FrameIds.ToArray();
+ var id = ids[random.Next(ids.Length)];
+ var data = pack.ReadJpeg(id);
+ Assert.NotNull(data);
+ Assert.BytesEqual(jpegs[id.ToByteArray()[0] | id.ToByteArray()[1] << 8], data);
+ reads++;
+ }
+ return reads;
+ })).ToArray();
+ var other = Task.Run(() =>
+ {
+ using var view = ThumbnailPack.Open(path, writable: false);
+ while (!done.IsCancellationRequested)
+ {
+ view.Refresh();
+ foreach (var id in view.FrameIds) Assert.NotNull(view.ReadJpeg(id));
+ }
+ });
+ await Task.WhenAll([writer, other, .. readers]);
+ Assert.Equal(200, pack.Count);
+ context.Log($"reads: {string.Join(", ", readers.Select(r => r.Result))}");
+ }
+
+ [Test]
+ public async Task CacheEvictsLeastRecentlyUsedAndCoalescesLoads()
+ {
+ var cache = new ThumbnailCache(3 * (300 + 64));
+ Thumbnail T() => new(10, 10, new byte[300]);
+ cache.Set(1, T());
+ cache.Set(2, T());
+ cache.Set(3, T());
+ Assert.True(cache.TryGet(1, out _));
+ cache.Set(4, T());
+ Assert.False(cache.TryGet(2, out _));
+ Assert.True(cache.TryGet(1, out _));
+ Assert.Equal(3, cache.Count);
+ Assert.LessOrEqual(cache.Bytes, cache.Budget);
+ cache.Set(5, new Thumbnail(100, 100, new byte[30000]));
+ Assert.False(cache.TryGet(5, out _));
+
+ var loads = 0;
+ var gate = new TaskCompletionSource();
+ async Task Loader(int key, CancellationToken ct)
+ {
+ Interlocked.Increment(ref loads);
+ await gate.Task;
+ return Thumbnail.FromJpeg(Jpeg(key));
+ }
+ var large = new ThumbnailCache(1 << 20);
+ var requests = Enumerable.Range(0, 10).Select(_ => large.GetOrLoadAsync(42, Loader)).ToArray();
+ gate.SetResult();
+ var results = await Task.WhenAll(requests);
+ Assert.Equal(1, loads);
+ Assert.True(results.All(r => ReferenceEquals(r, results[0])));
+ Assert.Equal(40, results[0]!.Width);
+ Assert.True(large.TryGet(42, out _));
+ }
+
+ [Test]
+ public void ProxyCarriesUprightPixelsAndCaptureExif()
+ {
+ var captured = new DateTime(2025, 7, 14, 21, 3, 9, DateTimeKind.Unspecified).AddTicks(4_500_000);
+ var metadata = new FrameMetadata { Make = "TestCam", Model = "T1", Orientation = 6, CapturedAt = captured, UtcOffsetMinutes = 120, Iso = 800, ExposureTime = 1 / 250.0 };
+ using var image = Frame(1, 2000, 1500);
+ var exif = ExifWriter.BuildTiff(metadata);
+ var source = Path.Combine(_dir, "src.jpg");
+ File.WriteAllBytes(source, JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = 90, App1Segments = [[.. "Exif\0\0"u8, .. exif]] }));
+
+ var proxy = ProxyBuilder.Write(DecoderFactory.CreateServer(), source, Path.Combine(_dir, "proxy.jpg"), ProxySize.Edge1280);
+ Assert.NotNull(proxy);
+ Assert.Equal(960, proxy!.Width);
+ Assert.Equal(1280, proxy.Height);
+ Assert.Equal(DecodeTier.Native, proxy.Tier);
+ var back = MetadataReader.Read(Path.Combine(_dir, "proxy.jpg"));
+ Assert.Equal(captured, back.CapturedAt);
+ Assert.Equal(120, back.UtcOffsetMinutes);
+ Assert.Equal(TimestampSource.ExifOriginal, back.TimestampSource);
+ Assert.Equal(1, back.Orientation);
+ Assert.Equal("TestCam", back.Make);
+ Assert.Equal(800, back.Iso);
+ Assert.Equal(960, back.Width);
+ Assert.Equal(1280, back.Height);
+ var info = JpegDecoder.ReadInfo(proxy.Jpeg);
+ Assert.Equal(960, info.Width);
+
+ var full = ProxyBuilder.Build(DecoderFactory.CreateServer(), source, ProxySize.Full);
+ Assert.Equal(1500, full!.Width);
+ }
+
+ [Test]
+ public void ProxyOfAnUnsupportedRawUsesThePreviewTier()
+ {
+ using var scene = SyntheticRaw.Smooth(96, 64);
+ var active = new RawRect(24, 4, 120, 68);
+ var cr2 = NativeRawWriters.Cr2(NativeRawWriters.Sensor(scene, "Canon EOS 5D Mark III", CfaPattern.Bayer("RGGB"), 128, 72, 24, 4, 2048, 16383), active, 1, "Canon EOS R99");
+ var path = Path.Combine(_dir, "x.cr2");
+ File.WriteAllBytes(path, cr2);
+ var proxy = ProxyBuilder.Build(DecoderFactory.CreateServer(), path);
+ Assert.Equal(DecodeTier.EmbeddedPreview, proxy!.Tier);
+ Assert.Equal(64, proxy.Width);
+ }
+}