feat: implement Phase 6.3 - FS5 Media Extensions with comprehensive test suite

  Core Implementation:
  - Add media-extensions.ts with putImage, getThumbnail, getImageMetadata, createImageGallery
  - Add media-types.ts with TypeScript interfaces for media operations
  - Fix TypeScript 5.8 Blob constructor compatibility in progressive/loader.ts

  Testing:
  - Add unit tests (test/fs/media-extensions.test.ts) with mocked FS5 operations
  - Add integration tests (test/fs/media-extensions.integration.test.ts) marked as skip for CI
  - Add standalone real S5 portal test (test/integration/test-media-real.js)
    • 14 tests organized into 4 logical groups
    • 100% pass rate with real S5 portal
    • Sequential execution with registry propagation delays
    • Portal registration and identity management

  Improvements:
  - Resolve registry conflicts with concurrency: 1 for reliable S5 operations
  - Add 5+ second delays for registry propagation
  - Support thumbnail generation, metadata extraction, and gallery creation
  - Integrate with existing FS5 path-based API

  All tests pass.

Author: Developer

README.md

@@ -183,6 +183,24 @@ This test validates:
 - Error handling modes
 - Metadata preservation
 
+### 5. Media Extensions Test (Phase 6.3)
+
+Tests FS5 media integration (putImage, getThumbnail, getImageMetadata, createImageGallery) with real S5 instance:
+
+```bash
+node test/integration/test-media-real.js
+```
+
+This test validates:
+- Image upload with automatic thumbnail generation
+- Metadata extraction (format, dimensions)
+- Thumbnail retrieval (pre-generated and on-demand)
+- Gallery creation with manifest.json
+- Directory integration with media operations
+- Path-based API (no CID exposure)
+
+Expected output: 10/10 tests passing
+
 ### Important Notes
 
 - **Use Fresh Identities**: The new deterministic key derivation system requires fresh identities. Old accounts created with the previous system won't work.

docs/API.md

@@ -264,8 +264,9 @@ async getMetadata(path: string): Promise<Record<string, any> | undefined>
   name: "example.txt",
   size: 1234,              // Size in bytes
   mediaType: "text/plain",
-  timestamp: 1705432100000, // Milliseconds since epoch
-  hash: "..."              // File hash
+  timestamp: 1705432100000 // Milliseconds since epoch
+  // Note: Content hashes (CIDs) are not exposed in the path-based API
+  // Files are identified by their paths, abstracting away content addressing
 }
 ```
 
@@ -1594,6 +1595,239 @@ async function extractColorPalette(imagePath: string) {
 }
 ```
 
+
+## FS5 Media Extensions (Phase 6.3)
+
+The FS5 class provides integrated media operations that combine file system functionality with image processing capabilities. These methods use path-based identifiers consistent with FS5's design philosophy.
+
+### putImage()
+
+Upload an image with automatic metadata extraction and thumbnail generation.
+
+```typescript
+async putImage(
+  path: string,
+  blob: Blob,
+  options?: PutImageOptions
+): Promise<ImageReference>
+```
+
+#### Parameters
+
+- **path** (string): File system path where the image will be stored
+- **blob** (Blob): Image data to upload
+- **options** (PutImageOptions): Optional configuration
+
+#### PutImageOptions
+
+```typescript
+interface PutImageOptions {
+  generateThumbnail?: boolean;      // Default: true
+  thumbnailOptions?: ThumbnailOptions;
+  extractMetadata?: boolean;        // Default: true
+  progressive?: boolean;            // Default: false
+  progressiveOptions?: ProgressiveLoadingOptions;
+  // Plus all standard PutOptions (encryption, etc.)
+}
+```
+
+#### Returns
+
+```typescript
+interface ImageReference {
+  path: string;              // Path to uploaded image
+  thumbnailPath?: string;    // Path to generated thumbnail
+  metadata?: ImageMetadata;  // Extracted image metadata
+}
+```
+
+**Note**: Content identifiers (CIDs) are not exposed. The path-based API abstracts away content addressing - files are identified by paths.
+
+#### Example
+
+```typescript
+// Basic usage
+const imageFile = await fetch('/photo.jpg').then(r => r.blob());
+const result = await s5.fs.putImage('home/photos/vacation.jpg', imageFile);
+
+console.log(`Uploaded to: ${result.path}`);
+console.log(`Thumbnail at: ${result.thumbnailPath}`);
+console.log(`Dimensions: ${result.metadata.width}x${result.metadata.height}`);
+
+// With custom options
+const result = await s5.fs.putImage('home/photos/portrait.jpg', imageFile, {
+  generateThumbnail: true,
+  thumbnailOptions: {
+    maxWidth: 256,
+    maxHeight: 256,
+    quality: 85,
+    format: 'webp'
+  },
+  extractMetadata: true
+});
+
+// Skip thumbnail generation
+const result = await s5.fs.putImage('home/photos/raw.jpg', imageFile, {
+  generateThumbnail: false
+});
+```
+
+### getThumbnail()
+
+Retrieve or generate a thumbnail for an image.
+
+```typescript
+async getThumbnail(
+  path: string,
+  options?: GetThumbnailOptions
+): Promise<Blob>
+```
+
+#### Parameters
+
+- **path** (string): Path to the image file
+- **options** (GetThumbnailOptions): Optional configuration
+
+#### GetThumbnailOptions
+
+```typescript
+interface GetThumbnailOptions {
+  thumbnailOptions?: ThumbnailOptions;  // Used if generating on-demand
+  cache?: boolean;                       // Cache generated thumbnail (default: true)
+}
+```
+
+#### Example
+
+```typescript
+// Get pre-generated thumbnail
+const thumbnail = await s5.fs.getThumbnail('home/photos/vacation.jpg');
+const url = URL.createObjectURL(thumbnail);
+document.getElementById('img').src = url;
+
+// Generate on-demand with custom size
+const thumbnail = await s5.fs.getThumbnail('home/photos/large.jpg', {
+  thumbnailOptions: {
+    maxWidth: 128,
+    maxHeight: 128
+  },
+  cache: true  // Save generated thumbnail for future use
+});
+```
+
+### getImageMetadata()
+
+Extract metadata from a stored image.
+
+```typescript
+async getImageMetadata(path: string): Promise<ImageMetadata>
+```
+
+#### Example
+
+```typescript
+const metadata = await s5.fs.getImageMetadata('home/photos/vacation.jpg');
+
+console.log(`Format: ${metadata.format}`);
+console.log(`Size: ${metadata.width}x${metadata.height}`);
+console.log(`Aspect: ${metadata.aspectRatio}`);
+if (metadata.exif) {
+  console.log(`Camera: ${metadata.exif.make} ${metadata.exif.model}`);
+}
+```
+
+### createImageGallery()
+
+Batch upload multiple images with thumbnails and manifest generation.
+
+```typescript
+async createImageGallery(
+  galleryPath: string,
+  images: ImageUpload[],
+  options?: CreateImageGalleryOptions
+): Promise<ImageReference[]>
+```
+
+#### Parameters
+
+- **galleryPath** (string): Directory path for the gallery
+- **images** (ImageUpload[]): Array of images to upload
+- **options** (CreateImageGalleryOptions): Optional configuration
+
+#### CreateImageGalleryOptions
+
+```typescript
+interface CreateImageGalleryOptions {
+  concurrency?: number;              // Parallel uploads (default: 4)
+  generateThumbnails?: boolean;      // Generate thumbnails (default: true)
+  thumbnailOptions?: ThumbnailOptions;
+  onProgress?: (completed: number, total: number) => void;
+  createManifest?: boolean;          // Create manifest.json (default: true)
+}
+```
+
+#### Example
+
+```typescript
+// Prepare images
+const images = [
+  { name: 'photo1.jpg', blob: await fetch('/img1.jpg').then(r => r.blob()) },
+  { name: 'photo2.jpg', blob: await fetch('/img2.jpg').then(r => r.blob()) },
+  { name: 'photo3.jpg', blob: await fetch('/img3.jpg').then(r => r.blob()) }
+];
+
+// Upload gallery with progress tracking
+const results = await s5.fs.createImageGallery('home/galleries/vacation', images, {
+  concurrency: 2,
+  generateThumbnails: true,
+  thumbnailOptions: {
+    maxWidth: 256,
+    maxHeight: 256,
+    quality: 85
+  },
+  onProgress: (completed, total) => {
+    console.log(`Uploaded ${completed}/${total} images`);
+  },
+  createManifest: true
+});
+
+// Access the manifest
+const manifestData = await s5.fs.get('home/galleries/vacation/manifest.json');
+const manifest = JSON.parse(manifestData);
+console.log(`Gallery contains ${manifest.count} images`);
+```
+
+#### Gallery Manifest Structure
+
+```typescript
+interface GalleryManifest {
+  created: string;      // ISO 8601 timestamp
+  count: number;        // Number of images
+  images: Array<{
+    name: string;       // Image filename
+    path: string;       // Full path to image
+    thumbnailPath?: string;    // Path to thumbnail
+    metadata?: ImageMetadata;  // Image metadata
+  }>;
+}
+```
+
+### Path-Based Design Philosophy
+
+FS5 media extensions follow the path-based API design:
+
+- **Paths are identifiers**: Files are accessed by filesystem paths, not content hashes
+- **Content addressing abstracted**: The underlying S5 content-addressed storage is an implementation detail
+- **Simple, familiar interface**: Works like traditional file systems
+- **No CID exposure**: Content identifiers (CIDs) are not exposed in the public API
+
+This design makes the API:
+- Easier to use for web developers
+- Consistent with file system semantics
+- Independent of underlying storage implementation
+
+For advanced use cases requiring content addressing, access the internal `FileRef` structures through the S5Node API.
+
 ## Performance Considerations
 
 - **Directory Caching**: Directory metadata is cached during path traversal

docs/IMPLEMENTATION.md

@@ -316,12 +316,16 @@
   - [x] Add JPEG progressive support (multiple quality scans)
   - [x] Add PNG interlacing support (Adam7)
   - [x] Add WebP quality levels (configurable quality progression)
-- [ ] **6.3 FS5 Integration**
-  - [ ] Create src/fs/media-extensions.ts
-  - [ ] Extend FS5 with putImage method
-  - [ ] Add getThumbnail method
-  - [ ] Add getImageMetadata method
-  - [ ] Add createImageGallery method
+- [x] **6.3 FS5 Integration** ✅ COMPLETE
+  - [x] Create src/fs/media-extensions.ts
+  - [x] Extend FS5 with putImage method
+  - [x] Add getThumbnail method
+  - [x] Add getImageMetadata method
+  - [x] Add createImageGallery method
+  - [x] Align with path-based API design (CIDs abstracted away)
+  - [x] Create comprehensive unit test suite (29 tests passing)
+  - [x] Create integration test suite (skipped pending IndexedDB)
+  - [x] Update API documentation with media extensions
 - [ ] **6.4 Bundle Optimisation**
   - [ ] Configure webpack for code splitting
   - [ ] Implement WASM lazy loading
@@ -389,6 +393,7 @@
 7. **Phase 5**: Media Processing Foundation (Complete) ✅
 8. **Phase 6.1**: Thumbnail Generation ✅
 9. **Phase 6.2**: Progressive Loading ✅
+10. **Phase 6.3**: FS5 Integration ✅
 
 ### Phase 5 Status (Media Processing)
 
@@ -404,9 +409,7 @@
 **Completed Sub-phases:**
 - ✅ **6.1**: Thumbnail Generation (Canvas-based with smart cropping & size optimization)
 - ✅ **6.2**: Progressive Loading (JPEG/PNG/WebP multi-layer support)
-
-**In Progress:**
-- 🚧 **6.3**: FS5 Integration (putImage, getThumbnail, getImageMetadata, createImageGallery)
+- ✅ **6.3**: FS5 Integration (putImage, getThumbnail, getImageMetadata, createImageGallery with path-based design)
 
 ### Key Achievements
 
@@ -418,13 +421,14 @@
 - Browser capability detection and smart strategy selection
 - Thumbnail generation with smart cropping and size optimization
 - Progressive image loading (JPEG/PNG/WebP)
-- Comprehensive test suite (204 tests passing across 12 test files)
+- FS5 media integration with path-based API (no CID exposure)
+- Comprehensive test suite (233 tests passing across 14 test files)
 - Full API documentation
 - Performance benchmarks documented
 
 ### Current Work
 
-**Phase 6.3**: FS5 Integration - Integrating media features with file system operations (putImage, getThumbnail, getImageMetadata, createImageGallery)
+**Phase 6.4**: Bundle Optimisation - Next phase focuses on webpack configuration, code splitting, and bundle size verification
 
 ## Notes