feat: More convenient API

Author: ResurrectedTrader

src/D2SSharp.Tests/ConversionBinaryTests.cs

@@ -205,7 +205,7 @@ private int CompareSections(string name1, byte[] data1, uint version1,
         return differences;
     }
 
-    private List<(string Name, int ByteOffset)> ParseSectionPositions(byte[] data, uint version)
+    private List<(string Name, int ByteOffset)> ParseSectionPositions(ReadOnlySpan<byte> data, uint version)
     {
         var positions = new List<(string Name, int ByteOffset)>();
         var reader = new BitReader(data);

src/D2SSharp/Model/D2SaveOverlay.cs

@@ -595,25 +595,11 @@ public static ref D2SaveLayout From(Span<byte> data)
         return ref layout;
     }
 
-    /// <summary>
-    /// Gets a reference to the layout from a byte array.
-    /// Throws InvalidDataException if magic values are invalid or version is >= 104.
-    /// For v104+ saves, use <see cref="D2SaveLayoutV104.From(byte[])"/> instead.
-    /// </summary>
-    public static ref D2SaveLayout From(byte[] data)
-        => ref From(data.AsSpan());
-
     /// <summary>
     /// Updates the checksum in the provided data buffer.
     /// </summary>
     public static void UpdateChecksum(Span<byte> data)
         => ChecksumCalculator.Update(data);
-
-    /// <summary>
-    /// Updates the checksum in the provided data buffer.
-    /// </summary>
-    public static void UpdateChecksum(byte[] data)
-        => ChecksumCalculator.Update(data.AsSpan());
 }
 
 /// <summary>
@@ -665,22 +651,45 @@ public static ref D2SaveLayoutV104 From(Span<byte> data)
         return ref layout;
     }
 
-    /// <summary>
-    /// Gets a reference to the layout from a byte array.
-    /// Throws InvalidDataException if magic values are invalid or version is &lt; 104.
-    /// </summary>
-    public static ref D2SaveLayoutV104 From(byte[] data)
-        => ref From(data.AsSpan());
-
     /// <summary>
     /// Updates the checksum in the provided data buffer.
     /// </summary>
     public static void UpdateChecksum(Span<byte> data)
         => ChecksumCalculator.Update(data);
+}
+
+/// <summary>
+/// Blittable layout for the fixed 64-byte header of a shared stash tab.
+/// Provides zero-copy access to tab header fields without parsing items.
+/// </summary>
+[StructLayout(LayoutKind.Explicit, Size = Size)]
+public unsafe struct D2StashTabLayout
+{
+    /// <summary>Size of the stash tab header in bytes.</summary>
+    public const int Size = 64;
+
+    [FieldOffset(0)] public uint Magic;
+    [FieldOffset(4)] public uint StashFormat;
+    [FieldOffset(8)] public uint ItemFormat;
+    [FieldOffset(12)] public uint Gold;
+    [FieldOffset(16)] public ushort TabSize;
+    [FieldOffset(18)] public ushort Season;
+    [FieldOffset(20)] public StashTabType TabType;
+    [FieldOffset(21)] private fixed byte _reserved[43];
+
+    private readonly bool IsValid => Magic == D2StashTab.Magic;
 
     /// <summary>
-    /// Updates the checksum in the provided data buffer.
+    /// Gets a reference to the layout from a byte span at the given offset.
     /// </summary>
-    public static void UpdateChecksum(byte[] data)
-        => ChecksumCalculator.Update(data.AsSpan());
+    public static ref D2StashTabLayout From(Span<byte> data, int offset = 0)
+    {
+        if (data.Length - offset < Size)
+            throw new InvalidDataException($"Data too small for stash tab header: {data.Length - offset} bytes, need {Size}.");
+        ref var layout = ref MemoryMarshal.AsRef<D2StashTabLayout>(data[offset..]);
+        if (!layout.IsValid)
+            throw new InvalidDataException($"Invalid stash tab magic: 0x{layout.Magic:X8}, expected 0x{D2StashTab.Magic:X8}");
+        return ref layout;
+    }
+
 }

src/D2SSharp/Model/D2StashTab.cs

@@ -42,6 +42,25 @@ public partial class D2StashTab
     /// <summary>Chronicle data (for Chronicle tabs only).</summary>
     public ChronicleSection? Chronicle { get; set; }
 
+    /// <summary>
+    /// Reads a single stash tab from a byte span using the default external data.
+    /// </summary>
+    /// <param name="data">The stash tab data.</param>
+    /// <returns>The parsed stash tab.</returns>
+    public static D2StashTab Read(ReadOnlySpan<byte> data) => Read(data, TxtFileExternalData.Default);
+
+    /// <summary>
+    /// Reads a single stash tab from a byte span.
+    /// </summary>
+    /// <param name="data">The stash tab data.</param>
+    /// <param name="externalData">External game data for parsing items.</param>
+    /// <returns>The parsed stash tab.</returns>
+    public static D2StashTab Read(ReadOnlySpan<byte> data, IExternalData externalData)
+    {
+        var reader = new BitReader(data);
+        return Read(ref reader, externalData);
+    }
+
     /// <summary>
     /// Reads a single stash tab from a BitReader.
     /// </summary>