refactor: Decouple asset resolver from markdown source and implement ReferencedAsset tracking

Changes to asset resolution architecture:
- Modified IAssetResolver to accept markdown source per-call instead of storing it as state
- Updated RelativePathAssetResolver to be stateless, receiving context file in ResolveAsync()
- Enables shared resolver instance across multiple pages without coupling

Introduced ReferencedAsset record:
- Captures complete asset reference info: original path, rewritten path, and resolved file
- Facilitates materialization in consumer code (PagesCommand)
- Replaces IFile collection with structured ReferencedAsset collection

AssetAwareHtmlTemplatedMarkdownFile improvements:
- Tracks all referenced assets (both included and referenced) via ReferencedAsset
- Unified asset processing for markdown source and template file detection
- Extracted ProcessAssetLinkAsync() method for shared pipeline logic

Virtual structure simplification:
- Removed automatic asset yielding from AssetAwareHtmlTemplatedMarkdownPageFolder
- Removed template asset yielding from HtmlTemplatedMarkdownPageFolder base class
- Assets now tracked in ReferencedAsset collection for explicit consumer materialization

Implemented PagesCommand:
- CLI command for multi-page blog generation using AssetAwareHtmlTemplatedMarkdownPagesFolder
- Materializes virtual structure by iterating page folders and copying files
- Uses ReferencedAsset.RewrittenPath for correct asset output placement

Added comprehensive test coverage:
- AssetAwareHtmlTemplatedMarkdownPagesFolderTests with 7 test cases
- Covers markdown discovery, hierarchy preservation, asset resolution, and link rewriting

Minor cleanup:
- Removed debug logging from PostPageAssetFolder
- Fixed formatting/whitespace in PostPageFolder and HtmlTemplatedMarkdownPageFolder
- Changed return types to IChildFolder for Pages-related classes

Author: Arlodotexe

src/Blog/Assets/IAssetResolver.cs

@@ -12,16 +12,12 @@ public interface IAssetResolver
     /// </summary>
     IFolder SourceFolder { get; init; }
 
-    /// <summary>
-    /// Markdown file for relative path context.
-    /// </summary>
-    IFile MarkdownSource { get; init; }
-
     /// <summary>
     /// Resolves a relative path string to an IFile instance.
     /// </summary>
+    /// <param name="markdownSource">Markdown file for relative path context (varies per page).</param>
     /// <param name="relativePath">The relative path to resolve.</param>
     /// <param name="ct">Cancellation token.</param>
     /// <returns>The resolved IFile, or null if not found.</returns>
-    Task<IFile?> ResolveAsync(string relativePath, CancellationToken ct = default);
+    Task<IFile?> ResolveAsync(IFile markdownSource, string relativePath, CancellationToken ct = default);
 }

src/Blog/Assets/ReferencedAsset.cs

@@ -0,0 +1,17 @@
+using OwlCore.Storage;
+
+namespace WindowsAppCommunity.Blog.Assets
+{
+    /// <summary>
+    /// Captures complete asset reference information for materialization.
+    /// Stores original detected path, rewritten path after strategy, and resolved file instance.
+    /// </summary>
+    /// <param name="OriginalPath">Path detected in markdown (relative to source file)</param>
+    /// <param name="RewrittenPath">Path after inclusion strategy applied (include vs reference)</param>
+    /// <param name="ResolvedFile">Actual file instance for copy operations</param>
+    public record ReferencedAsset(
+        string OriginalPath,
+        string RewrittenPath,
+        IFile ResolvedFile
+    );
+}

src/Blog/Assets/RelativePathAssetResolver.cs

@@ -5,17 +5,15 @@ namespace WindowsAppCommunity.Blog.Assets;
 /// <summary>
 /// Resolves relative paths to IFile instances using source folder and markdown file context.
 /// Paths are resolved relative to the markdown file's location (pre-folderization).
+/// Stateless design - markdown source passed per-call to support shared resolver across pages.
 /// </summary>
 public sealed class RelativePathAssetResolver : IAssetResolver
 {
     /// <inheritdoc/>
     public required IFolder SourceFolder { get; init; }
 
     /// <inheritdoc/>
-    public required IFile MarkdownSource { get; init; }
-
-    /// <inheritdoc/>
-    public async Task<IFile?> ResolveAsync(string relativePath, CancellationToken ct = default)
+    public async Task<IFile?> ResolveAsync(IFile markdownSource, string relativePath, CancellationToken ct = default)
     {
         if (string.IsNullOrWhiteSpace(relativePath))
             return null;
@@ -27,7 +25,7 @@ public sealed class RelativePathAssetResolver : IAssetResolver
 
             // Resolve relative to markdown file's location (pre-folderization)
             // The markdown file itself is the base for relative path resolution
-            var item = await MarkdownSource.GetItemByRelativePathAsync(normalizedPath, ct);
+            var item = await markdownSource.GetItemByRelativePathAsync(normalizedPath, ct);
 
             // Return only if it's a file
             return item as IFile;

src/Blog/Page/AssetAwareHtmlTemplatedMarkdownFile.cs

@@ -15,7 +15,9 @@ namespace WindowsAppCommunity.Blog.Page
     /// </summary>
     public sealed class AssetAwareHtmlTemplatedMarkdownFile : HtmlTemplatedMarkdownFile
     {
-        private readonly List<IFile> _includedAssets = new();
+        private readonly List<ReferencedAsset> _includedAssets = new();
+        private readonly IStorable _templateSource;
+        private readonly string? _templateFileName;
 
         /// <summary>
         /// Creates asset-aware virtual HTML file with lazy markdown→HTML generation and asset management.
@@ -33,6 +35,8 @@ public AssetAwareHtmlTemplatedMarkdownFile(
             IFolder? parent = null)
             : base(id, markdownSource, templateSource, templateFileName, parent)
         {
+            _templateSource = templateSource;
+            _templateFileName = templateFileName;
         }
 
         /// <summary>
@@ -51,14 +55,15 @@ public AssetAwareHtmlTemplatedMarkdownFile(
         public required IAssetInclusionStrategy InclusionStrategy { get; init; }
 
         /// <summary>
-        /// Assets that were decided for inclusion (self-contained in page folder).
-        /// Exposed to containing folder for yielding in virtual structure.
+        /// All assets referenced by the markdown file (both included and referenced).
+        /// Exposed to containing folder for materialization to output.
         /// </summary>
-        public IReadOnlyCollection<IFile> IncludedAssets => _includedAssets.AsReadOnly();
+        public IReadOnlyCollection<ReferencedAsset> IncludedAssets => _includedAssets.AsReadOnly();
 
         /// <summary>
         /// Post-process HTML with asset management pipeline.
         /// Detects links → Resolves to files → Decides include/reference via path rewriting → Tracks included assets.
+        /// Detects links from BOTH markdown source AND template file to unify asset handling.
         /// </summary>
         /// <param name="html">Rendered HTML from template</param>
         /// <param name="model">Data model used for rendering</param>
@@ -69,41 +74,54 @@ protected override async Task<string> PostProcessHtmlAsync(string html, PostPage
             // Clear included assets from any previous generation
             _includedAssets.Clear();
 
-            // Detect asset links in rendered HTML output (pass self as IFile)
-            await foreach (var originalPath in LinkDetector.DetectAsync(this, ct))
+            // Detect asset links from markdown source (content-referenced assets)
+            await foreach (var originalPath in LinkDetector.DetectAsync(MarkdownSource, ct))
             {
-                // Resolve path to IFile
-                var resolvedAsset = await Resolver.ResolveAsync(originalPath, ct);
-
-                // Null resolver policy: Skip if not found (preserve broken link)
-                if (resolvedAsset == null)
-                {
-                    continue;
-                }
+                html = await ProcessAssetLinkAsync(html, MarkdownSource, originalPath, ct);
+            }
 
-                // Strategy decides include vs reference by returning rewritten path
-                // Path structure determines behavior:
-                // - Child path (no ../ prefix): Include
-                // - Parent path (../ prefix): Reference
-                var rewrittenPath = await InclusionStrategy.DecideAsync(
-                    MarkdownSource,  // Pass original markdown source (not virtual HTML)
-                    resolvedAsset,
-                    originalPath,
-                    ct);
+            return html;
+        }
 
-                // Implicit decision based on path structure
-                if (!rewrittenPath.StartsWith("../"))
-                {
-                    // Include: Add to tracked assets (will be yielded by containing folder)
-                    _includedAssets.Add(resolvedAsset);
-                }
-                // Reference: Asset not added to included list (stays external)
+        /// <summary>
+        /// Process a single detected asset link through the asset pipeline.
+        /// Shared logic for both markdown and template asset detection.
+        /// </summary>
+        /// <param name="html">HTML content to update</param>
+        /// <param name="contextFile">File providing resolution context (markdown or template)</param>
+        /// <param name="originalPath">Original asset path as detected</param>
+        /// <param name="ct">Cancellation token</param>
+        /// <returns>Updated HTML with rewritten link</returns>
+        private async Task<string> ProcessAssetLinkAsync(
+            string html, 
+            IFile contextFile, 
+            string originalPath, 
+            CancellationToken ct)
+        {
+            // Resolve path to IFile (pass context file for resolution)
+            var resolvedAsset = await Resolver.ResolveAsync(contextFile, originalPath, ct);
 
-                // Rewrite link in HTML (applies to both Include and Reference)
-                html = html.Replace(originalPath, rewrittenPath);
+            // Null resolver policy: Skip if not found (preserve broken link)
+            if (resolvedAsset == null)
+            {
+                return html;
             }
 
-            return html;
+            // Strategy decides include vs reference by returning rewritten path
+            // Path structure determines behavior:
+            // - Child path (no ../ prefix): Include
+            // - Parent path (../ prefix): Reference
+            var rewrittenPath = await InclusionStrategy.DecideAsync(
+                contextFile,
+                resolvedAsset,
+                originalPath,
+                ct);
+
+            // Track all referenced assets for materialization
+            _includedAssets.Add(new ReferencedAsset(originalPath, rewrittenPath, resolvedAsset));
+
+            // Rewrite link in HTML (strategy determines path prefix)
+            return html.Replace(originalPath, rewrittenPath);
         }
     }
 }

src/Blog/Page/AssetAwareHtmlTemplatedMarkdownPageFolder.cs

@@ -80,15 +80,6 @@ public override async IAsyncEnumerable<IStorableChild> GetItemsAsync(
                 // Pass through other items (template assets)
                 yield return item;
             }
-
-            // Yield markdown-referenced assets that were decided for inclusion
-            if (assetAwareFile != null && (type == StorableType.All || type == StorableType.File))
-            {
-                foreach (var includedAsset in assetAwareFile.IncludedAssets)
-                {
-                    yield return (IStorableChild)includedAsset;
-                }
-            }
         }
     }
 }

src/Blog/Page/HtmlTemplatedMarkdownPageFolder.cs

@@ -15,7 +15,7 @@ namespace WindowsAppCommunity.Blog.Page
     /// Base class - wraps markdown source file and template to provide virtual {filename}/index.html + assets structure.
     /// Implements lazy generation - no file system operations during construction.
     /// </summary>
-    public class HtmlTemplatedMarkdownPageFolder : IFolder
+    public class HtmlTemplatedMarkdownPageFolder : IChildFolder
     {
         private readonly IFile _markdownSource;
         private readonly IStorable _templateSource;
@@ -72,10 +72,9 @@ public virtual async IAsyncEnumerable<IStorableChild> GetItemsAsync(
             StorableType type = StorableType.All,
             [EnumeratorCancellation] CancellationToken cancellationToken = default)
         {
-            // Resolve template file for exclusion and HtmlTemplatedMarkdownFile construction
-            var templateFile = await ResolveTemplateFileAsync(_templateSource, _templateFileName);
-
-            // Yield HtmlTemplatedMarkdownFile (virtual HTML file)
+            // Yield HtmlTemplatedMarkdownFile (virtual HTML file) only
+            // Template assets are NOT yielded here - they're detected as links in the template HTML
+            // and tracked in the HTML file's IncludedAssets collection for consumer materialization
             if (type == StorableType.All || type == StorableType.File)
             {
                 var indexHtmlId = $"{Id}/index.html";
@@ -84,32 +83,6 @@ public virtual async IAsyncEnumerable<IStorableChild> GetItemsAsync(
                     Name = "index.html"
                 };
             }
-
-            // If template is folder, yield wrapped asset structure
-            if (_templateSource is IFolder templateFolder)
-            {
-                await foreach (var item in templateFolder.GetItemsAsync(StorableType.All, cancellationToken))
-                {
-                    // Wrap subfolders as PostPageAssetFolder
-                    if (item is IFolder subfolder && (type == StorableType.All || type == StorableType.Folder))
-                    {
-                        yield return new PostPageAssetFolder(subfolder, this, templateFile);
-                        continue;
-                    }
-
-                    // Pass through files directly (excluding template HTML file)
-                    if (item is IChildFile file && (type == StorableType.All || type == StorableType.File))
-                    {
-                        // Exclude template HTML file (already rendered as index.html)
-                        if (file.Id == templateFile.Id)
-                        {
-                            continue;
-                        }
-
-                        yield return file;
-                    }
-                }
-            }
         }
 
         /// <summary>
@@ -155,16 +128,13 @@ private async Task<IFile> ResolveTemplateFileAsync(
 
                 if (templateFile is not IFile resolvedFile)
                 {
-                    throw new FileNotFoundException(
-                        $"Template file '{fileName}' not found in folder '{folder.Name}'.");
+                    throw new FileNotFoundException($"Template file '{fileName}' not found in folder '{folder.Name}'.");
                 }
 
                 return resolvedFile;
             }
 
-            throw new ArgumentException(
-                $"Template source must be IFile or IFolder, got: {templateSource.GetType().Name}",
-                nameof(templateSource));
+            throw new ArgumentException($"Template source must be IFile or IFolder, got: {templateSource.GetType().Name}", nameof(templateSource));
         }
     }
 }

src/Blog/Pages/AssetAwareHtmlTemplatedMarkdownPagesFolder.cs

@@ -16,7 +16,7 @@ namespace WindowsAppCommunity.Blog.Pages
     /// Asset-aware only variant (no non-asset-aware needed for multi-page scenario).
     /// Implements lazy generation - no file system operations during construction.
     /// </summary>
-    public class AssetAwareHtmlTemplatedMarkdownPagesFolder : IFolder
+    public class AssetAwareHtmlTemplatedMarkdownPagesFolder : IChildFolder
     {
         private readonly IFolder _markdownSourceFolder;
         private readonly IStorable _templateSource;
@@ -82,18 +82,15 @@ public async IAsyncEnumerable<IStorableChild> GetItemsAsync(StorableType type =
                 {
                     if (type == StorableType.All || type == StorableType.Folder)
                     {
-                        var pageFolder = new AssetAwareHtmlTemplatedMarkdownPageFolder(
-                            file,
-                            _templateSource,
-                            _templateFileName)
+                        var pageFolder = new AssetAwareHtmlTemplatedMarkdownPageFolder(file, _templateSource, _templateFileName)
                         {
                             LinkDetector = LinkDetector,
                             Resolver = Resolver,
                             InclusionStrategy = InclusionStrategy,
                             Parent = this
                         };
 
-                        yield return (IStorableChild)pageFolder;
+                        yield return pageFolder;
                     }
                 }
 
@@ -102,18 +99,15 @@ public async IAsyncEnumerable<IStorableChild> GetItemsAsync(StorableType type =
                 {
                     if (type == StorableType.All || type == StorableType.Folder)
                     {
-                        var nestedPagesFolder = new AssetAwareHtmlTemplatedMarkdownPagesFolder(
-                            subfolder,
-                            _templateSource,
-                            _templateFileName)
+                        var nestedPagesFolder = new AssetAwareHtmlTemplatedMarkdownPagesFolder(subfolder, _templateSource, _templateFileName)
                         {
                             LinkDetector = LinkDetector,
                             Resolver = Resolver,
                             InclusionStrategy = InclusionStrategy,
                             Parent = this
                         };
 
-                        yield return (IStorableChild)nestedPagesFolder;
+                        yield return nestedPagesFolder;
                     }
                 }
             }

src/Blog/PostPage/PostPageAssetFolder.cs

@@ -53,8 +53,6 @@ public async IAsyncEnumerable<IStorableChild> GetItemsAsync(
             StorableType type = StorableType.All,
             [EnumeratorCancellation] CancellationToken cancellationToken = default)
         {
-            OwlCore.Diagnostics.Logger.LogInformation($"PostPageAssetFolder.GetItemsAsync starting for: {_wrappedFolder.Id}");
-            
             // Enumerate wrapped folder items
             await foreach (var item in _wrappedFolder.GetItemsAsync(type, cancellationToken))
             {
@@ -77,8 +75,6 @@ public async IAsyncEnumerable<IStorableChild> GetItemsAsync(
                     yield return file;
                 }
             }
-            
-            OwlCore.Diagnostics.Logger.LogInformation($"PostPageAssetFolder.GetItemsAsync complete for: {_wrappedFolder.Id}");
         }
     }
 }

src/Blog/PostPage/PostPageFolder.cs

@@ -94,8 +94,7 @@ private string SanitizeFilename(string markdownFilename)
 
             // Replace invalid filename characters with underscore
             var invalidChars = Path.GetInvalidFileNameChars();
-            var sanitized = string.Concat(nameWithoutExtension.Select(c => 
-                invalidChars.Contains(c) ? '_' : c));
+            var sanitized = string.Concat(nameWithoutExtension.Select(c => invalidChars.Contains(c) ? '_' : c));
 
             return sanitized;
         }
@@ -124,16 +123,13 @@ private async Task<IFile> ResolveTemplateFileAsync(
 
                 if (templateFile is not IFile resolvedFile)
                 {
-                    throw new FileNotFoundException(
-                        $"Template file '{fileName}' not found in folder '{folder.Name}'.");
+                    throw new FileNotFoundException($"Template file '{fileName}' not found in folder '{folder.Name}'.");
                 }
 
                 return resolvedFile;
             }
 
-            throw new ArgumentException(
-                $"Template source must be IFile or IFolder, got: {templateSource.GetType().Name}",
-                nameof(templateSource));
+            throw new ArgumentException($"Template source must be IFile or IFolder, got: {templateSource.GetType().Name}", nameof(templateSource));
         }
     }
 }