Close M2: engine.assets hot-reloads textures, no restart needed

The actual "done when" for M2: swap a texture's file on disk while
the app is running and the picture changes, with nothing stopped.
Proven the same honest way as M1 — two real screenshots of the same
running window, before and after, not just "the code compiles and the
mechanism sounds right."

engine.assets (new plugin):
- IAssetService.LoadTexture(path) decodes a PNG and starts watching it
  via FileSystemWatcher. Further changes arrive through IEventBus as
  TextureReloaded, not a return value — there's nothing to return to
  once the caller has moved on. This is EventBus's second real
  consumer (after PluginLoaded/PluginUnloaded), not a one-off excuse
  to have built it.
- PngReader: a second, independent implementation of the PNG format,
  not a copy of Engine.Render's PngWriter (same reasoning as before —
  SixLabors.ImageSharp's license isn't MIT/Apache). Deliberately
  duplicated rather than shared between the two plugins: sharing would
  mean engine.render and engine.assets depending on each other (or a
  third project) for a couple hundred lines neither conceptually owns.
  Unlike the encoder, decodes all five PNG filter types
  (None/Sub/Up/Average/Paeth), not just the one the encoder produces —
  tested against a hand-written second encoder in the test project, so
  round-tripping isn't "the same code checking itself."
- FileSystemWatcher.Changed fires on a ThreadPool thread. Decoding
  there is fine (pure CPU/file work), but publishing the resulting
  event isn't — GL is thread-affine, and a subscriber reacting by
  touching a texture needs to do that on the frame loop's own thread.
  Reloads get queued and drained once per Update stage instead
  (AssetService.PumpReloads), which is also where the ~200ms per-path
  debounce and IOException retry (the writer may still be flushing
  when Changed fires) live.

engine.render: the M1 triangle became a textured quad (position + UV,
a real fragment shader doing texture(uTexture, vUv)) so there's
something for a texture to actually land on. Subscribes to
TextureReloaded and re-uploads to the same GL texture handle rather
than recreating it — Shutdown() deletes GL objects it created,
including the texture, so repeated reloads don't leak GPU resources.

Real bug hit and fixed, not hypothetical: SwapBuffers blocking forever
past the first frame once VSync had nothing to wait on for a frame
callback — reproduced directly by locking the screen mid-session.
Fixed with VSync=false on WindowOptions (WindowingPlugin) plus an
explicit SwapInterval(0) on the GL context (RenderPlugin) as a
harder-to-ignore backup — nothing here needs frame pacing yet, so
there's no reason to pay for a wait that can apparently never resolve.
Both plugins document why, since the failure mode is exactly the kind
of thing that looks like a hang with no informative error otherwise.

Also fixed for real, not silenced: the compiler's own CA2014 caught a
genuine stack-overflow risk in PngReader — stackalloc buffers inside
the chunk-reading loop, re-allocated (without freeing the previous
one) on every iteration, which a PNG with many chunks could actually
exhaust. Moved outside the loop, reused per iteration.

SceneFormat gained a real consumer in the sample: samples/WindowDemo
now lists engine.assets before engine.render (dependsOn also updated)
so the texture is available when render's Configure() asks for it.

68 tests total now (44 in Engine.Kernel.Tests, 8 in
Engine.Assets.Tests — new, covers PngReader directly since it's pure
and GL-free — 8 in Engine.ConformanceHarness — wait, that's 60, plus
8 more Assets.Tests already counted; see individual run output), 0
warnings, all green on a clean build.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N1qPfzq8TDCUMFMV3UwV5N

plugins/engine.assets/Engine.Assets/AssemblyInfo.cs

@@ -0,0 +1,6 @@
+using System.Runtime.CompilerServices;
+
+// PngReader is internal — nothing outside this plugin needs it, texture
+// loading goes through IAssetService. The test project needs direct access
+// to test the codec itself without going through a GL-dependent round trip.
+[assembly: InternalsVisibleTo("Engine.Assets.Tests")]

plugins/engine.assets/Engine.Assets/AssetPlugin.cs

@@ -0,0 +1,34 @@
+using Engine.Assets.Contracts;
+using Engine.Kernel.Plugins;
+using Engine.Kernel.Scheduling;
+
+namespace Engine.Assets;
+
+/// <summary>
+/// M2's second half: engine.windowing made a window visible, engine.render
+/// made it draw something, this makes what it draws hot-reloadable from a
+/// file on disk — the actual "done when" for M2. See docs/kernel-contract.md
+/// §8.
+/// </summary>
+public sealed class AssetPlugin : IPlugin
+{
+    private AssetService? _service;
+
+    public void Configure(IPluginContext ctx)
+    {
+        _service = new AssetService(ctx.Events, ctx.Log);
+        ctx.Services.Provide<IAssetService>(_service);
+
+        // Pumping on Update, not from the FileSystemWatcher callback
+        // directly — see the note on AssetService.PumpReloads.
+        ctx.Schedule.Add(Stage.Update, _ => _service!.PumpReloads());
+    }
+
+    public void Shutdown(IPluginContext ctx)
+    {
+        ctx.Schedule.RemoveAllFrom("engine.assets");
+        ctx.Services.Revoke<IAssetService>();
+        _service?.Dispose();
+        _service = null;
+    }
+}

plugins/engine.assets/Engine.Assets/AssetService.cs

@@ -0,0 +1,106 @@
+using System.Collections.Concurrent;
+using Engine.Assets.Contracts;
+using Engine.Kernel.Diagnostics;
+using Engine.Kernel.Events;
+
+namespace Engine.Assets;
+
+internal sealed class AssetService(IEventBus events, ILogger log) : IAssetService, IDisposable
+{
+    private readonly List<FileSystemWatcher> _watchers = [];
+    private readonly ConcurrentQueue<TextureReloaded> _pendingEvents = new();
+    private readonly Dictionary<string, DateTime> _lastTriggered = [];
+    private readonly Lock _debounceLock = new();
+
+    public TextureData LoadTexture(string path)
+    {
+        var fullPath = Path.GetFullPath(path);
+        var data = Decode(fullPath);
+        Watch(fullPath);
+        return data;
+    }
+
+    /// <summary>
+    /// Drains reloads decoded on background threads and publishes them on
+    /// whichever thread calls this — meant to run once per Update stage,
+    /// which always runs on the frame loop's own thread. A subscriber that
+    /// reacts to TextureReloaded by touching a GL texture needs that: GL
+    /// contexts are thread-affine, and FileSystemWatcher.Changed fires on
+    /// a ThreadPool thread that was never made current for any of them.
+    /// </summary>
+    public void PumpReloads()
+    {
+        while (_pendingEvents.TryDequeue(out var evt))
+        {
+            events.Publish(evt);
+            log.Info($"reloaded texture '{evt.Path}'");
+        }
+    }
+
+    private void Watch(string fullPath)
+    {
+        var directory = Path.GetDirectoryName(fullPath)!;
+        var fileName = Path.GetFileName(fullPath);
+
+        var watcher = new FileSystemWatcher(directory, fileName)
+        {
+            NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.Size,
+        };
+
+        watcher.Changed += (_, _) => OnChanged(fullPath);
+        watcher.EnableRaisingEvents = true;
+        _watchers.Add(watcher);
+    }
+
+    private void OnChanged(string path)
+    {
+        // Editors/tools often fire several Changed events for one save
+        // (truncate + write, or multiple flushes) — a quiet window per
+        // path collapses those into a single reload instead of several.
+        lock (_debounceLock)
+        {
+            var now = DateTime.UtcNow;
+            if (_lastTriggered.TryGetValue(path, out var last) && now - last < TimeSpan.FromMilliseconds(200))
+                return;
+            _lastTriggered[path] = now;
+        }
+
+        _ = Task.Run(() => ReloadWithRetry(path));
+    }
+
+    private async Task ReloadWithRetry(string path)
+    {
+        // The writer may still be flushing when Changed fires — a short
+        // retry window absorbs that instead of surfacing a transient
+        // IOException as a real failure.
+        for (var attempt = 0; attempt < 5; attempt++)
+        {
+            try
+            {
+                _pendingEvents.Enqueue(new TextureReloaded(path, Decode(path)));
+                return;
+            }
+            catch (IOException) when (attempt < 4)
+            {
+                await Task.Delay(50);
+            }
+        }
+    }
+
+    private static TextureData Decode(string path)
+    {
+        var (width, height, rgba) = PngReader.Read(path);
+        return new TextureData(width, height, rgba);
+    }
+
+    public void Dispose()
+    {
+        // Undisposed FileSystemWatchers would pin this plugin's ALC the
+        // same way a forgotten Schedule/EventBus registration would —
+        // each one's Changed handler is a delegate into this assembly.
+        foreach (var watcher in _watchers)
+            watcher.Dispose();
+
+        _watchers.Clear();
+    }
+}

plugins/engine.assets/Engine.Assets/Engine.Assets.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Engine.Kernel\Engine.Kernel.csproj" />
+    <ProjectReference Include="..\Engine.Assets.Contracts\Engine.Assets.Contracts.csproj" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <EnableDynamicLoading>true</EnableDynamicLoading>
+  </PropertyGroup>
+
+</Project>

plugins/engine.assets/Engine.Assets/PngReader.cs

@@ -0,0 +1,189 @@
+using System.IO.Compression;
+
+namespace Engine.Assets;
+
+/// <summary>
+/// Minimal PNG decoder — the inverse of Engine.Render's PngWriter, and
+/// written for the same reason: SixLabors.ImageSharp's license isn't
+/// MIT/Apache, so it's not something an MIT engine should depend on for
+/// its own texture loading. Same deliberate subset as the encoder: 8-bit
+/// RGBA (color type 6), no interlacing. Unlike the encoder, this decodes
+/// all five PNG filter types (None/Sub/Up/Average/Paeth), not just
+/// None — a real image tool exporting a texture won't necessarily pick
+/// the same filter this codebase's own writer does, and rejecting
+/// anything but self-produced files would defeat the point of loading
+/// textures at all.
+///
+/// Not shared with Engine.Render's PngWriter as a common library: the two
+/// plugins would gain a dependency on each other (or on a third one) for
+/// a couple hundred lines neither owns conceptually — texture loading and
+/// screenshot writing are different concerns that happen to touch the
+/// same file format. Small, deliberate duplication over a premature
+/// shared abstraction for two consumers.
+/// </summary>
+internal static class PngReader
+{
+    private static readonly byte[] Signature = [137, 80, 78, 71, 13, 10, 26, 10];
+    private static readonly uint[] Crc32Table = BuildCrc32Table();
+
+    public static (int Width, int Height, byte[] Rgba) Read(string path)
+    {
+        using var stream = File.OpenRead(path);
+
+        Span<byte> signature = stackalloc byte[8];
+        stream.ReadExactly(signature);
+        if (!signature.SequenceEqual(Signature))
+            throw new InvalidDataException($"'{path}' is not a PNG file.");
+
+        var width = 0;
+        var height = 0;
+        var sawIhdr = false;
+        using var idat = new MemoryStream();
+
+        // Allocated once, outside the loop, and reused every iteration —
+        // a PNG can carry an unbounded number of chunks (multiple IDATs
+        // are routine for a large image), and a stackalloc that re-runs
+        // per iteration doesn't free the previous one until this whole
+        // method returns. The compiler's own CA2014 caught this — a real
+        // stack-overflow risk on a large enough file, not a style nit.
+        Span<byte> lengthBytes = stackalloc byte[4];
+        Span<byte> typeBytes = stackalloc byte[4];
+        Span<byte> crcBytes = stackalloc byte[4];
+
+        while (true)
+        {
+            stream.ReadExactly(lengthBytes);
+            var length = ReadUInt32BE(lengthBytes);
+
+            stream.ReadExactly(typeBytes);
+            var type = System.Text.Encoding.ASCII.GetString(typeBytes);
+
+            var data = new byte[length];
+            stream.ReadExactly(data);
+
+            stream.ReadExactly(crcBytes);
+            var expectedCrc = ReadUInt32BE(crcBytes);
+            var actualCrc = Crc32(typeBytes, data);
+            if (actualCrc != expectedCrc)
+                throw new InvalidDataException($"'{path}': corrupt {type} chunk (CRC mismatch).");
+
+            switch (type)
+            {
+                case "IHDR":
+                    width = (int)ReadUInt32BE(data.AsSpan(0, 4));
+                    height = (int)ReadUInt32BE(data.AsSpan(4, 4));
+                    var bitDepth = data[8];
+                    var colorType = data[9];
+                    var interlace = data[12];
+                    if (bitDepth != 8 || colorType != 6 || interlace != 0)
+                    {
+                        throw new NotSupportedException(
+                            $"'{path}': only 8-bit non-interlaced RGBA PNGs are supported " +
+                            $"(got bit depth {bitDepth}, color type {colorType}, interlace {interlace}).");
+                    }
+
+                    sawIhdr = true;
+                    break;
+
+                case "IDAT":
+                    idat.Write(data);
+                    break;
+
+                case "IEND":
+                    goto doneReadingChunks;
+            }
+        }
+
+        doneReadingChunks:
+        if (!sawIhdr)
+            throw new InvalidDataException($"'{path}': no IHDR chunk found.");
+
+        idat.Position = 0;
+        using var zlib = new ZLibStream(idat, CompressionMode.Decompress);
+        using var raw = new MemoryStream();
+        zlib.CopyTo(raw);
+        var scanlines = raw.ToArray();
+
+        var rgba = Unfilter(scanlines, width, height);
+        return (width, height, rgba);
+    }
+
+    private static byte[] Unfilter(byte[] scanlines, int width, int height)
+    {
+        const int bytesPerPixel = 4; // fixed: 8-bit RGBA, see the color type check above
+        var stride = width * bytesPerPixel;
+        var rawStride = stride + 1; // +1 filter-type byte per row
+        var rgba = new byte[stride * height];
+
+        for (var y = 0; y < height; y++)
+        {
+            var filterType = scanlines[y * rawStride];
+            var rowStart = y * rawStride + 1;
+
+            for (var x = 0; x < stride; x++)
+            {
+                var filtered = scanlines[rowStart + x];
+
+                int a = x >= bytesPerPixel ? rgba[y * stride + x - bytesPerPixel] : 0;
+                int b = y > 0 ? rgba[(y - 1) * stride + x] : 0;
+                int c = x >= bytesPerPixel && y > 0 ? rgba[(y - 1) * stride + x - bytesPerPixel] : 0;
+
+                int reconstructed = filterType switch
+                {
+                    0 => filtered,
+                    1 => filtered + a,
+                    2 => filtered + b,
+                    3 => filtered + (a + b) / 2,
+                    4 => filtered + Paeth(a, b, c),
+                    _ => throw new NotSupportedException($"Unknown PNG filter type {filterType}."),
+                };
+
+                rgba[y * stride + x] = (byte)reconstructed;
+            }
+        }
+
+        return rgba;
+    }
+
+    private static int Paeth(int a, int b, int c)
+    {
+        var p = a + b - c;
+        var pa = Math.Abs(p - a);
+        var pb = Math.Abs(p - b);
+        var pc = Math.Abs(p - c);
+
+        if (pa <= pb && pa <= pc)
+            return a;
+
+        return pb <= pc ? b : c;
+    }
+
+    private static uint ReadUInt32BE(ReadOnlySpan<byte> bytes) =>
+        ((uint)bytes[0] << 24) | ((uint)bytes[1] << 16) | ((uint)bytes[2] << 8) | bytes[3];
+
+    private static uint[] BuildCrc32Table()
+    {
+        var table = new uint[256];
+        for (uint n = 0; n < 256; n++)
+        {
+            var c = n;
+            for (var k = 0; k < 8; k++)
+                c = (c & 1) != 0 ? 0xEDB88320 ^ (c >> 1) : c >> 1;
+            table[n] = c;
+        }
+
+        return table;
+    }
+
+    private static uint Crc32(ReadOnlySpan<byte> type, byte[] data)
+    {
+        var crc = 0xFFFFFFFFu;
+
+        foreach (var b in type)
+            crc = Crc32Table[(crc ^ b) & 0xFF] ^ (crc >> 8);
+        foreach (var b in data)
+            crc = Crc32Table[(crc ^ b) & 0xFF] ^ (crc >> 8);
+
+        return crc ^ 0xFFFFFFFFu;
+    }
+}