feat(pub): implement image handling in markdown conversion with tests

* replace AssertErrorContains with shared implementation across services and tests

cmd/commands_test.go

···
 
 	"github.com/stormlightlabs/noteleaf/internal/handlers"
 	"github.com/stormlightlabs/noteleaf/internal/services"
+	"github.com/stormlightlabs/noteleaf/internal/shared"
 )
 
 func setupCommandTest(t *testing.T) func() {
···
 			if err == nil {
 				t.Error("expected movie add command to fail when search fails")
 			}
-			services.AssertErrorContains(t, err, "search failed")
+			shared.AssertErrorContains(t, err, "search failed", "")
 		})
 
 		t.Run("remove command with non-existent movie ID", func(t *testing.T) {
···
 			if err == nil {
 				t.Error("expected tv add command to fail when search fails")
 			}
-			services.AssertErrorContains(t, err, "tv search failed")
+			shared.AssertErrorContains(t, err, "tv search failed", "")
 		})
 
 		t.Run("remove command with non-existent TV show ID", func(t *testing.T) {

internal/handlers/publication.go

···
 		return fmt.Errorf("failed to get session: %w", err)
 	}
 
+	// TODO: Implement image handling for markdown conversion
+	// 1. Extract note's directory from filepath/database
+	// 2. Create LocalImageResolver with BlobUploader that calls h.atproto.UploadBlob()
+	// 3. Use converter.WithImageResolver(resolver, noteDir) before ToLeaflet()
+	// This will upload images to AT Protocol and get real CIDs/dimensions
 	converter := public.NewMarkdownConverter()
 	blocks, err := converter.ToLeaflet(note.Content)
 	if err != nil {
···
 		return fmt.Errorf("failed to get session: %w", err)
 	}
 
+	// TODO: Implement image handling for markdown conversion (same as Post method)
+	// 1. Extract note's directory from filepath/database
+	// 2. Create LocalImageResolver with BlobUploader that calls h.atproto.UploadBlob()
+	// 3. Use converter.WithImageResolver(resolver, noteDir) before ToLeaflet()
+	// This will upload images to AT Protocol and get real CIDs/dimensions
 	converter := public.NewMarkdownConverter()
 	blocks, err := converter.ToLeaflet(note.Content)
 	if err != nil {

internal/public/convert.go

···
 // Package public provides conversion between markdown and leaflet block formats
 //
-// TODO: Handle overlapping facets
-// TODO: Implement image handling - requires blob resolution
+// Image handling follows a two-pass approach:
+//  1. Gather all image URLs from the markdown AST
+//  2. Resolve images (fetch bytes, get dimensions, upload to blob storage)
+//  3. Convert markdown to blocks using the resolved image metadata
 package public
 
 import (
 	"bytes"
 	"fmt"
+	"image"
+	_ "image/gif"
+	_ "image/jpeg"
+	_ "image/png"
+	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/gomarkdown/markdown/ast"
···
 	FromLeaflet(blocks []BlockWrap) (string, error)
 }
 
+// ImageInfo contains resolved image metadata
+type ImageInfo struct {
+	Blob   Blob
+	Width  int
+	Height int
+}
+
+// ImageResolver resolves image URLs to blob data and metadata
+type ImageResolver interface {
+	// ResolveImage resolves an image URL to blob data and dimensions
+	// The url parameter may be a local file path or remote URL
+	ResolveImage(url string) (*ImageInfo, error)
+}
+
+// LocalImageResolver resolves local file paths to image metadata
+type LocalImageResolver struct {
+	// BlobUploader is called to upload image bytes and get a blob reference
+	// If nil, creates a placeholder blob with a hash-based CID
+	//
+	// TODO: CLI commands that publish documents must provide this function to upload
+	// images to AT Protocol blob storage via com.atproto.repo.uploadBlob
+	BlobUploader func(data []byte, mimeType string) (Blob, error)
+}
+
+// ResolveImage reads a local image file and extracts metadata
+func (r *LocalImageResolver) ResolveImage(path string) (*ImageInfo, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read image: %w", err)
+	}
+
+	img, format, err := image.DecodeConfig(bytes.NewReader(data))
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode image: %w", err)
+	}
+
+	mimeType := "image/" + format
+
+	var blob Blob
+	if r.BlobUploader != nil {
+		blob, err = r.BlobUploader(data, mimeType)
+		if err != nil {
+			return nil, fmt.Errorf("failed to upload blob: %w", err)
+		}
+	} else {
+		blob = Blob{
+			Type:     TypeBlob,
+			Ref:      CID{Link: "bafkreiplaceholder"},
+			MimeType: mimeType,
+			Size:     len(data),
+		}
+	}
+
+	return &ImageInfo{
+		Blob:   blob,
+		Width:  img.Width,
+		Height: img.Height,
+	}, nil
+}
+
 // MarkdownConverter implements the [Converter] interface
 type MarkdownConverter struct {
-	extensions parser.Extensions
+	extensions    parser.Extensions
+	imageResolver ImageResolver
+	basePath      string // Base path for resolving relative image paths
 }
 
 type formatContext struct {
···
 	return &MarkdownConverter{
 		extensions: extensions,
 	}
+}
+
+// WithImageResolver sets an image resolver for the converter
+func (c *MarkdownConverter) WithImageResolver(resolver ImageResolver, basePath string) *MarkdownConverter {
+	c.imageResolver = resolver
+	c.basePath = basePath
+	return c
 }
 
 // ToLeaflet converts markdown to leaflet blocks
 func (c *MarkdownConverter) ToLeaflet(markdown string) ([]BlockWrap, error) {
 	p := parser.NewWithExtensions(c.extensions)
 	doc := p.Parse([]byte(markdown))
+	imageURLs := c.gatherImages(doc)
+
+	resolvedImages := make(map[string]*ImageInfo)
+	if c.imageResolver != nil {
+		for _, url := range imageURLs {
+			resolvedPath := url
+			if !filepath.IsAbs(url) && c.basePath != "" {
+				resolvedPath = filepath.Join(c.basePath, url)
+			}
+
+			info, err := c.imageResolver.ResolveImage(resolvedPath)
+			if err != nil {
+				return nil, fmt.Errorf("failed to resolve image %s: %w", url, err)
+			}
+			resolvedImages[url] = info
+		}
+	}
 
 	var blocks []BlockWrap
 
 	for _, child := range doc.GetChildren() {
 		switch n := child.(type) {
 		case *ast.Heading:
-			if block := c.convertHeading(n); block != nil {
+			if block := c.convertHeading(n, resolvedImages); block != nil {
 				blocks = append(blocks, *block)
 			}
 		case *ast.Paragraph:
-			if block := c.convertParagraph(n); block != nil {
-				blocks = append(blocks, *block)
-			}
+			convertedBlocks := c.convertParagraph(n, resolvedImages)
+			blocks = append(blocks, convertedBlocks...)
 		case *ast.CodeBlock:
 			if block := c.convertCodeBlock(n); block != nil {
 				blocks = append(blocks, *block)
 			}
 		case *ast.BlockQuote:
-			if block := c.convertBlockquote(n); block != nil {
+			if block := c.convertBlockquote(n, resolvedImages); block != nil {
 				blocks = append(blocks, *block)
 			}
 		case *ast.List:
-			if block := c.convertList(n); block != nil {
+			if block := c.convertList(n, resolvedImages); block != nil {
 				blocks = append(blocks, *block)
 			}
 		case *ast.HorizontalRule:
···
 					Type: TypeHorizontalRuleBlock,
 				},
 			})
+		case *ast.Image:
+			if block := c.convertImage(n, resolvedImages); block != nil {
+				blocks = append(blocks, *block)
+			}
 		}
 	}
 
 	return blocks, nil
 }
 
+// gatherImages walks the AST and collects all image URLs
+func (c *MarkdownConverter) gatherImages(node ast.Node) []string {
+	var urls []string
+
+	ast.WalkFunc(node, func(n ast.Node, entering bool) ast.WalkStatus {
+		if !entering {
+			return ast.GoToNext
+		}
+
+		if img, ok := n.(*ast.Image); ok {
+			urls = append(urls, string(img.Destination))
+		}
+
+		return ast.GoToNext
+	})
+
+	return urls
+}
+
 // convertHeading converts an AST heading to a leaflet HeaderBlock
-func (c *MarkdownConverter) convertHeading(node *ast.Heading) *BlockWrap {
-	text, facets := c.extractTextAndFacets(node)
+func (c *MarkdownConverter) convertHeading(node *ast.Heading, resolvedImages map[string]*ImageInfo) *BlockWrap {
+	text, facets, _ := c.extractTextAndFacets(node, resolvedImages)
 	return &BlockWrap{
 		Type: TypeBlock,
 		Block: HeaderBlock{
···
 	}
 }
 
-// convertParagraph converts an AST paragraph to a leaflet TextBlock
-func (c *MarkdownConverter) convertParagraph(node *ast.Paragraph) *BlockWrap {
-	text, facets := c.extractTextAndFacets(node)
+// convertParagraph converts an AST paragraph to leaflet blocks
+func (c *MarkdownConverter) convertParagraph(node *ast.Paragraph, resolvedImages map[string]*ImageInfo) []BlockWrap {
+	text, facets, imageBlocks := c.extractTextAndFacets(node, resolvedImages)
+
+	if len(imageBlocks) > 0 {
+		return imageBlocks
+	}
+
 	if strings.TrimSpace(text) == "" {
 		return nil
 	}
 
-	return &BlockWrap{
+	return []BlockWrap{{
 		Type: TypeBlock,
 		Block: TextBlock{
 			Type:      TypeTextBlock,
 			Plaintext: text,
 			Facets:    facets,
 		},
-	}
+	}}
 }
 
 // convertCodeBlock converts an AST code block to a leaflet CodeBlock
···
 }
 
 // convertBlockquote converts an AST blockquote to a leaflet BlockquoteBlock
-func (c *MarkdownConverter) convertBlockquote(node *ast.BlockQuote) *BlockWrap {
-	text, facets := c.extractTextAndFacets(node)
+func (c *MarkdownConverter) convertBlockquote(node *ast.BlockQuote, resolvedImages map[string]*ImageInfo) *BlockWrap {
+	text, facets, _ := c.extractTextAndFacets(node, resolvedImages)
 	return &BlockWrap{
 		Type: TypeBlock,
 		Block: BlockquoteBlock{
···
 }
 
 // convertList converts an AST list to a leaflet UnorderedListBlock
-func (c *MarkdownConverter) convertList(node *ast.List) *BlockWrap {
+func (c *MarkdownConverter) convertList(node *ast.List, resolvedImages map[string]*ImageInfo) *BlockWrap {
 	var items []ListItem
 
 	for _, child := range node.Children {
 		if listItem, ok := child.(*ast.ListItem); ok {
-			item := c.convertListItem(listItem)
+			item := c.convertListItem(listItem, resolvedImages)
 			if item != nil {
 				items = append(items, *item)
 			}
···
 }
 
 // convertListItem converts an AST list item to a leaflet ListItem
-func (c *MarkdownConverter) convertListItem(node *ast.ListItem) *ListItem {
-	text, facets := c.extractTextAndFacets(node)
+func (c *MarkdownConverter) convertListItem(node *ast.ListItem, resolvedImages map[string]*ImageInfo) *ListItem {
+	text, facets, _ := c.extractTextAndFacets(node, resolvedImages)
 	return &ListItem{
 		Type: TypeListItem,
 		Content: TextBlock{
···
 	}
 }
 
-// extractTextAndFacets extracts plaintext and facets from an AST node
-func (c *MarkdownConverter) extractTextAndFacets(node ast.Node) (string, []Facet) {
+// convertImage converts an AST image to a leaflet ImageBlock
+func (c *MarkdownConverter) convertImage(node *ast.Image, resolvedImages map[string]*ImageInfo) *BlockWrap {
+	alt := string(node.Title)
+	if alt == "" {
+		for _, child := range node.Children {
+			if text, ok := child.(*ast.Text); ok {
+				alt = string(text.Literal)
+				break
+			}
+		}
+	}
+
+	info, hasInfo := resolvedImages[string(node.Destination)]
+
+	var blob Blob
+	var aspectRatio AspectRatio
+
+	if hasInfo {
+		blob = info.Blob
+		aspectRatio = AspectRatio{
+			Type:   TypeAspectRatio,
+			Width:  info.Width,
+			Height: info.Height,
+		}
+	} else {
+		blob = Blob{
+			Type:     TypeBlob,
+			Ref:      CID{Link: "bafkreiplaceholder"},
+			MimeType: "image/jpeg",
+			Size:     0,
+		}
+		aspectRatio = AspectRatio{
+			Type:   TypeAspectRatio,
+			Width:  1,
+			Height: 1,
+		}
+	}
+
+	return &BlockWrap{
+		Type: TypeBlock,
+		Block: ImageBlock{
+			Type:        TypeImageBlock,
+			Image:       blob,
+			Alt:         alt,
+			AspectRatio: aspectRatio,
+		},
+	}
+}
+
+// extractTextAndFacets extracts plaintext, facets, and image blocks from an AST node
+func (c *MarkdownConverter) extractTextAndFacets(node ast.Node, resolvedImages map[string]*ImageInfo) (string, []Facet, []BlockWrap) {
 	var buf bytes.Buffer
 	var facets []Facet
+	var blocks []BlockWrap
 	offset := 0
 
 	var stack []formatContext
···
 				buf.WriteString(content)
 
 				if len(stack) > 0 {
-					ctx := stack[len(stack)-1]
+					var allFeatures []FacetFeature
+					for _, ctx := range stack {
+						allFeatures = append(allFeatures, ctx.features...)
+					}
 					facet := Facet{
 						Type: TypeFacet,
 						Index: ByteSlice{
···
 							ByteStart: offset,
 							ByteEnd:   offset + len(content),
 						},
-						Features: ctx.features,
+						Features: allFeatures,
 					}
 					facets = append(facets, facet)
 				}
···
 					stack = stack[:len(stack)-1]
 				}
 			}
+		case *ast.Image:
+			if entering {
+				if buf.Len() > 0 {
+					blocks = append(blocks, BlockWrap{
+						Type: TypeBlock,
+						Block: TextBlock{
+							Type:      TypeTextBlock,
+							Plaintext: buf.String(),
+							Facets:    facets,
+						},
+					})
+					buf.Reset()
+					facets = nil
+					offset = 0
+				}
+
+				if imgBlock := c.convertImage(v, resolvedImages); imgBlock != nil {
+					blocks = append(blocks, *imgBlock)
+				}
+			}
 		case *ast.Softbreak, *ast.Hardbreak:
 			if entering {
 				buf.WriteString(" ")
···
 		}
 		return ast.GoToNext
 	})
-	return buf.String(), facets
+
+	// If we created blocks, add any remaining text
+	if len(blocks) > 0 && buf.Len() > 0 {
+		blocks = append(blocks, BlockWrap{
+			Type: TypeBlock,
+			Block: TextBlock{
+				Type:      TypeTextBlock,
+				Plaintext: buf.String(),
+				Facets:    facets,
+			},
+		})
+	}
+
+	return buf.String(), facets, blocks
 }
 
 // FromLeaflet converts leaflet blocks back to markdown

internal/public/convert_test.go

···
 package public
 
 import (
+	"image"
+	"image/png"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
···
 
 			shared.AssertTrue(t, len(text.Facets) >= 3, "should have at least 3 facets")
 		})
+
+		t.Run("handles overlapping bold and italic", func(t *testing.T) {
+			markdown := "***bold and italic***"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertEqual(t, "bold and italic", text.Plaintext, "text should be correct")
+			shared.AssertTrue(t, len(text.Facets) > 0, "should have facets")
+
+			facet := text.Facets[0]
+			shared.AssertEqual(t, 2, len(facet.Features), "should have 2 features")
+
+			hasBold := false
+			hasItalic := false
+			for _, feature := range facet.Features {
+				switch feature.(type) {
+				case FacetBold:
+					hasBold = true
+				case FacetItalic:
+					hasItalic = true
+				}
+			}
+			shared.AssertTrue(t, hasBold, "should have bold feature")
+			shared.AssertTrue(t, hasItalic, "should have italic feature")
+		})
+
+		t.Run("handles nested bold in italic", func(t *testing.T) {
+			markdown := "*italic **and bold** still italic*"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertEqual(t, "italic and bold still italic", text.Plaintext, "text should be correct")
+			shared.AssertTrue(t, len(text.Facets) >= 2, "should have multiple facets")
+
+			foundOverlap := false
+			for _, facet := range text.Facets {
+				if strings.Contains(text.Plaintext[facet.Index.ByteStart:facet.Index.ByteEnd], "and bold") {
+					shared.AssertTrue(t, len(facet.Features) >= 2, "overlapping section should have multiple features")
+					foundOverlap = true
+				}
+			}
+			shared.AssertTrue(t, foundOverlap, "should find overlapping facet")
+		})
+
+		t.Run("handles link with formatting", func(t *testing.T) {
+			markdown := "[**bold link**](https://example.com)"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertEqual(t, "bold link", text.Plaintext, "text should be correct")
+			shared.AssertTrue(t, len(text.Facets) > 0, "should have facets")
+
+			hasLink := false
+			hasBold := false
+			for _, facet := range text.Facets {
+				for _, feature := range facet.Features {
+					switch f := feature.(type) {
+					case FacetLink:
+						hasLink = true
+						shared.AssertEqual(t, "https://example.com", f.URI, "link URI should match")
+					case FacetBold:
+						hasBold = true
+					}
+				}
+			}
+			shared.AssertTrue(t, hasLink, "should have link feature")
+			shared.AssertTrue(t, hasBold, "should have bold feature")
+		})
+
+		t.Run("handles strikethrough with bold", func(t *testing.T) {
+			markdown := "~~**deleted bold**~~"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertEqual(t, "deleted bold", text.Plaintext, "text should be correct")
+			shared.AssertTrue(t, len(text.Facets) > 0, "should have facets")
+
+			hasStrike := false
+			hasBold := false
+			for _, facet := range text.Facets {
+				for _, feature := range facet.Features {
+					switch feature.(type) {
+					case FacetStrikethrough:
+						hasStrike = true
+					case FacetBold:
+						hasBold = true
+					}
+				}
+			}
+			shared.AssertTrue(t, hasStrike, "should have strikethrough feature")
+			shared.AssertTrue(t, hasBold, "should have bold feature")
+		})
+
+		t.Run("handles complex nested formatting", func(t *testing.T) {
+			markdown := "*italic **bold and italic** italic*"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			foundBoldItalic := false
+			for _, facet := range text.Facets {
+				content := text.Plaintext[facet.Index.ByteStart:facet.Index.ByteEnd]
+				if strings.Contains(content, "bold and italic") {
+					shared.AssertTrue(t, len(facet.Features) >= 2, "nested section should have multiple features")
+					foundBoldItalic = true
+				}
+			}
+			shared.AssertTrue(t, foundBoldItalic, "should find nested bold and italic section")
+		})
 	})
 
 	t.Run("Round-trip Conversion", func(t *testing.T) {
···
 			blocks, err := converter.ToLeaflet(markdown)
 			shared.AssertNoError(t, err, "should succeed")
 			shared.AssertEqual(t, 2, len(blocks), "should have 2 blocks")
+		})
+	})
+
+	t.Run("Image Handling", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		createTestImage := func(t *testing.T, name string, width, height int) string {
+			path := filepath.Join(tmpDir, name)
+
+			img := image.NewRGBA(image.Rect(0, 0, width, height))
+			f, err := os.Create(path)
+			shared.AssertNoError(t, err, "should create image file")
+			defer f.Close()
+
+			err = png.Encode(f, img)
+			shared.AssertNoError(t, err, "should encode image")
+
+			return path
+		}
+
+		t.Run("converts image without resolver (placeholder)", func(t *testing.T) {
+			markdown := "![alt text](image.png)"
+			converter := NewMarkdownConverter()
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertTrue(t, len(blocks) >= 1, "should have at least 1 block")
+
+			var imgBlock ImageBlock
+			found := false
+			for _, block := range blocks {
+				if img, ok := block.Block.(ImageBlock); ok {
+					imgBlock = img
+					found = true
+					break
+				}
+			}
+
+			shared.AssertTrue(t, found, "should find image block")
+			shared.AssertEqual(t, TypeImageBlock, imgBlock.Type, "type should match")
+			shared.AssertEqual(t, "alt text", imgBlock.Alt, "alt text should match")
+			shared.AssertEqual(t, "bafkreiplaceholder", imgBlock.Image.Ref.Link, "should have placeholder CID")
+		})
+
+		t.Run("resolves local image with dimensions", func(t *testing.T) {
+			_ = createTestImage(t, "test.png", 800, 600)
+			markdown := "![test image](test.png)"
+
+			resolver := &LocalImageResolver{}
+			converter := NewMarkdownConverter().WithImageResolver(resolver, tmpDir)
+
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertTrue(t, len(blocks) >= 1, "should have at least 1 block")
+
+			var imgBlock ImageBlock
+			found := false
+			for _, block := range blocks {
+				if img, ok := block.Block.(ImageBlock); ok {
+					imgBlock = img
+					found = true
+					break
+				}
+			}
+
+			shared.AssertTrue(t, found, "should find image block")
+			shared.AssertEqual(t, "test image", imgBlock.Alt, "alt text should match")
+			shared.AssertEqual(t, 800, imgBlock.AspectRatio.Width, "width should match")
+			shared.AssertEqual(t, 600, imgBlock.AspectRatio.Height, "height should match")
+			shared.AssertEqual(t, "image/png", imgBlock.Image.MimeType, "mime type should match")
+		})
+
+		t.Run("handles inline images in paragraph", func(t *testing.T) {
+			_ = createTestImage(t, "inline.png", 100, 100)
+			markdown := "Some text before ![inline](inline.png) and text after"
+
+			resolver := &LocalImageResolver{}
+			converter := NewMarkdownConverter().WithImageResolver(resolver, tmpDir)
+
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertTrue(t, len(blocks) >= 2, "should have multiple blocks for inline images")
+
+			textBlock1, ok := blocks[0].Block.(TextBlock)
+			shared.AssertTrue(t, ok, "first block should be text")
+			shared.AssertTrue(t, strings.Contains(textBlock1.Plaintext, "Some text before"), "should contain text before image")
+
+			imgBlock, ok := blocks[1].Block.(ImageBlock)
+			shared.AssertTrue(t, ok, "second block should be image")
+			shared.AssertEqual(t, "inline", imgBlock.Alt, "alt text should match")
+		})
+
+		t.Run("handles multiple images", func(t *testing.T) {
+			_ = createTestImage(t, "img1.png", 200, 150)
+			_ = createTestImage(t, "img2.png", 300, 200)
+			markdown := "![first](img1.png)\n\n![second](img2.png)"
+
+			resolver := &LocalImageResolver{}
+			converter := NewMarkdownConverter().WithImageResolver(resolver, tmpDir)
+
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+
+			var imageBlocks []ImageBlock
+			for _, block := range blocks {
+				if img, ok := block.Block.(ImageBlock); ok {
+					imageBlocks = append(imageBlocks, img)
+				}
+			}
+
+			shared.AssertEqual(t, 2, len(imageBlocks), "should have 2 image blocks")
+			shared.AssertEqual(t, "first", imageBlocks[0].Alt, "first alt text")
+			shared.AssertEqual(t, 200, imageBlocks[0].AspectRatio.Width, "first width")
+			shared.AssertEqual(t, "second", imageBlocks[1].Alt, "second alt text")
+			shared.AssertEqual(t, 300, imageBlocks[1].AspectRatio.Width, "second width")
+		})
+
+		t.Run("uses custom blob uploader", func(t *testing.T) {
+			_ = createTestImage(t, "upload.png", 100, 100)
+			markdown := "![uploaded](upload.png)"
+
+			uploadCalled := false
+			resolver := &LocalImageResolver{
+				BlobUploader: func(data []byte, mimeType string) (Blob, error) {
+					uploadCalled = true
+					shared.AssertEqual(t, "image/png", mimeType, "mime type should be png")
+					shared.AssertTrue(t, len(data) > 0, "should have data")
+
+					return Blob{
+						Type:     TypeBlob,
+						Ref:      CID{Link: "bafkreicustomcid"},
+						MimeType: mimeType,
+						Size:     len(data),
+					}, nil
+				},
+			}
+
+			converter := NewMarkdownConverter().WithImageResolver(resolver, tmpDir)
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertTrue(t, uploadCalled, "upload should be called")
+
+			imgBlock, ok := blocks[0].Block.(ImageBlock)
+			shared.AssertTrue(t, ok, "block should be image")
+			shared.AssertEqual(t, "bafkreicustomcid", imgBlock.Image.Ref.Link, "should use custom CID")
+		})
+
+		t.Run("handles missing image gracefully", func(t *testing.T) {
+			markdown := "![missing](nonexistent.png)"
+			resolver := &LocalImageResolver{}
+			converter := NewMarkdownConverter().WithImageResolver(resolver, tmpDir)
+
+			_, err := converter.ToLeaflet(markdown)
+			shared.AssertError(t, err, "should error on missing image")
+			shared.AssertTrue(t, strings.Contains(err.Error(), "failed to resolve image"), "error should mention resolution failure")
+		})
+
+		t.Run("gathers images from complex document", func(t *testing.T) {
+			_ = createTestImage(t, "header.png", 100, 100)
+			_ = createTestImage(t, "body.png", 200, 200)
+			_ = createTestImage(t, "list.png", 50, 50)
+
+			markdown := `# Header
+
+![header image](header.png)
+
+Some text with ![inline](body.png) image.
+
+- List item
+- Another item with ![list img](list.png)
+`
+
+			resolver := &LocalImageResolver{}
+			converter := NewMarkdownConverter().WithImageResolver(resolver, tmpDir)
+
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+
+			imageCount := 0
+			for _, block := range blocks {
+				if _, ok := block.Block.(ImageBlock); ok {
+					imageCount++
+				}
+			}
+			shared.AssertTrue(t, imageCount >= 2, "should find multiple images")
+		})
+
+		t.Run("preserves image dimensions accurately", func(t *testing.T) {
+			testCases := []struct {
+				name   string
+				width  int
+				height int
+			}{
+				{"square.png", 100, 100},
+				{"landscape.png", 1920, 1080},
+				{"portrait.png", 1080, 1920},
+				{"wide.png", 2560, 1440},
+			}
+
+			for _, tc := range testCases {
+				createTestImage(t, tc.name, tc.width, tc.height)
+				markdown := "![test](" + tc.name + ")"
+
+				resolver := &LocalImageResolver{}
+				converter := NewMarkdownConverter().WithImageResolver(resolver, tmpDir)
+
+				blocks, err := converter.ToLeaflet(markdown)
+				shared.AssertNoError(t, err, "should convert "+tc.name)
+
+				imgBlock := blocks[0].Block.(ImageBlock)
+				shared.AssertEqual(t, tc.width, imgBlock.AspectRatio.Width, tc.name+" width")
+				shared.AssertEqual(t, tc.height, imgBlock.AspectRatio.Height, tc.name+" height")
+			}
 		})
 	})
 }

internal/services/media_test.go

···
 	"testing"
 
 	"github.com/stormlightlabs/noteleaf/internal/models"
+	"github.com/stormlightlabs/noteleaf/internal/shared"
 )
 
 func TestMediaServices(t *testing.T) {
···
 
 				service := CreateMovieService()
 				_, err := service.Search(context.Background(), "error", 1, 10)
-				AssertErrorContains(t, err, "search error")
+				shared.AssertErrorContains(t, err, "search error", "")
 			})
 		})
 
···
 
 				service := CreateMovieService()
 				_, err := service.Get(context.Background(), "error")
-				AssertErrorContains(t, err, "fetch error")
+				shared.AssertErrorContains(t, err, "fetch error", "")
 			})
 		})
 
···
 
 				service := CreateMovieService()
 				err := service.Check(context.Background())
-				AssertErrorContains(t, err, "html fetch error")
+				shared.AssertErrorContains(t, err, "html fetch error", "")
 			})
 		})
 
···
 
 				service := CreateTVService()
 				_, err := service.Search(context.Background(), "error", 1, 10)
-				AssertErrorContains(t, err, "search error")
+				shared.AssertErrorContains(t, err, "search error", "")
 			})
 		})
 
···
 
 				service := CreateTVService()
 				_, err := service.Get(context.Background(), "error")
-				AssertErrorContains(t, err, "fetch error")
+				shared.AssertErrorContains(t, err, "fetch error", "")
 			})
 		})
 
···
 
 				service := CreateTVService()
 				err := service.Check(context.Background())
-				AssertErrorContains(t, err, "html fetch error")
+				shared.AssertErrorContains(t, err, "html fetch error", "")
 			})
 		})
 	})

internal/services/services_test.go

···
 				t.Error("Search should return error for API failure")
 			}
 
-			AssertErrorContains(t, err, "API returned status 500")
+			shared.AssertErrorContains(t, err, "API returned status 500", "")
 		})
 
 		t.Run("handles malformed JSON", func(t *testing.T) {
···
 				t.Error("Search should return error for malformed JSON")
 			}
 
-			AssertErrorContains(t, err, "failed to decode response")
+			shared.AssertErrorContains(t, err, "failed to decode response", "")
 		})
 
 		t.Run("handles context cancellation", func(t *testing.T) {
···
 				t.Error("Get should return error for non-existent work")
 			}
 
-			AssertErrorContains(t, err, "book not found")
+			shared.AssertErrorContains(t, err, "book not found", "")
 		})
 
 		t.Run("handles API error", func(t *testing.T) {
···
 				t.Error("Get should return error for API failure")
 			}
 
-			AssertErrorContains(t, err, "API returned status 500")
+			shared.AssertErrorContains(t, err, "API returned status 500", "")
 		})
 	})
 
···
 				t.Error("Check should return error for API failure")
 			}
 
-			AssertErrorContains(t, err, "open Library API returned status 503")
+			shared.AssertErrorContains(t, err, "open Library API returned status 503", "")
 		})
 
 		t.Run("handles network error", func(t *testing.T) {

internal/services/test_utilities.go

···
 	t.Errorf("expected to find TV show containing '%s' in results", expectedTitle)
 }
 
-// AssertErrorContains checks that an error contains the expected message
-func AssertErrorContains(t *testing.T, err error, expectedMsg string) {
-	t.Helper()
-
-	if err == nil {
-		t.Fatalf("expected error containing '%s', got nil", expectedMsg)
-	}
-	if !strings.Contains(err.Error(), expectedMsg) {
-		t.Errorf("expected error to contain '%s', got '%v'", expectedMsg, err)
-	}
-}
-
 // CreateMovieService returns a new movie service for testing
 func CreateMovieService() *MovieService {
 	return NewMovieService()