portapack 0.2.1 → 0.3.1

package/tests/unit/core/extractor.test.ts

@@ -1,1129 +1,673 @@
 /**
- * @file extractor.test.ts
- * @description Unit tests for asset extraction logic (extractAssets function). Perseverance! 💪
- * @version 1.1.3 - Fixed TypeScript errors related to Jest matchers and variable names.
+ * @file src/core/extractor.test.ts
+ * @description Unit tests for asset extraction logic (extractAssets function)
  */
 
 // === Imports ===
+import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import path from 'path';
+import { fileURLToPath, pathToFileURL, URL } from 'url';
+// Use specific imports from 'fs' and 'fs/promises' where needed
+import * as fsPromises from 'fs/promises'; // For mocking readFile
+import * as fs from 'fs'; // For mocking statSync etc.
 import type { PathLike } from 'fs';
 import type { FileHandle } from 'fs/promises';
-import type { OpenMode, Stats, StatSyncOptions } from 'node:fs';
-import * as fs from 'fs';
-import path from 'path';
-import type { AxiosRequestConfig, AxiosResponse, AxiosError, InternalAxiosRequestConfig, AxiosRequestHeaders, AxiosHeaderValue } from 'axios';
-import * as axiosNs from 'axios';
-import { URL, fileURLToPath } from 'url';
-// Adjust path based on your project structure (e.g., src -> ../../..)
-import type { ParsedHTML, Asset } from '../../../src/types'; // Assuming types.ts is correct
-import { LogLevel } from '../../../src/types';
-import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals'; // Ensure expect is imported if needed explicitly
-// Adjust path based on your project structure
-import { Logger } from '../../../src/utils/logger';
-
-// =================== MOCK SETUP (Refined) ===================
-
-// --- Type Signatures for Mock Functions ---
-type AxiosGetSig = (url: string, config?: AxiosRequestConfig) => Promise<AxiosResponse<Buffer>>;
-type ReadFileBufferSig = ( path: PathLike | FileHandle, options?: { encoding?: null | undefined; flag?: OpenMode | undefined; signal?: AbortSignal | undefined; } | null | undefined ) => Promise<Buffer>;
-type StatSyncSig = (path: fs.PathLike, options?: StatSyncOptions | undefined) => fs.Stats;
-
-// --- Mock Functions ---
-const mockReadFileFn = jest.fn<ReadFileBufferSig>();
-const mockAxiosGetFn = jest.fn<AxiosGetSig>();
-const mockStatSyncFn = jest.fn<StatSyncSig>();
-
-// --- Mock Modules (BEFORE importing the code under test) ---
-jest.unstable_mockModule('fs/promises', () => ({ readFile: mockReadFileFn }));
-jest.unstable_mockModule('fs', () => ({
-    statSync: mockStatSyncFn,
-    // Spread other fs functions if needed, but ensure statSync is the mock
-     ...Object.fromEntries(Object.entries(fs).filter(([key]) => key !== 'statSync')),
-}));
-jest.unstable_mockModule('axios', () => ({
-    __esModule: true,
-    default: { get: mockAxiosGetFn, isAxiosError: axiosNs.isAxiosError },
-    isAxiosError: axiosNs.isAxiosError,
-    AxiosHeaders: axiosNs.AxiosHeaders, // Ensure AxiosHeaders is exported correctly
-}));
-
-
-// --- Import Code Under Test (AFTER mocks are set up) ---
-const { extractAssets } = await import('../../../src/core/extractor');
-
-// --- Mock Refs (Convenience variables for the mocked functions) ---
-const mockedReadFile = mockReadFileFn;
-const mockedAxiosGet = mockAxiosGetFn;
-const mockedStatSync = mockStatSyncFn;
-
-// === Test Constants ===
+import type { OpenMode, Stats, StatSyncOptions, BigIntStats } from 'node:fs'; // Use node: prefix
+// Import types from the project
+import type { Asset, ParsedHTML } from '../../../src/types'; // Adjust path as needed
+import { LogLevel } from '../../../src/types'; // Adjust path as needed
+import { Logger } from '../../../src/utils/logger'; // Adjust path as needed
+// Import necessary axios types and the namespace
+import type {
+    AxiosResponse,
+    AxiosRequestConfig,
+    AxiosError,
+    AxiosHeaderValue,
+    AxiosRequestHeaders,
+    AxiosResponseHeaders,
+    InternalAxiosRequestConfig
+} from 'axios';
+import * as axiosNs from 'axios'; // Namespace import
+import { AxiosHeaders } from 'axios'; // Import AxiosHeaders class if used directly
+
+// =================== MOCK SETUP ===================
+
+// --- Apply Mocks (Using jest.mock at top level) ---
+// Mock the entire 'fs/promises', 'fs', and 'axios' modules
+jest.mock('fs/promises');
+jest.mock('fs');
+jest.mock('axios');
+
+// --- Define Mock Function Variable Types ---
+// Use jest.MockedFunction for type safety with mocked modules
+type MockedReadFileFn = jest.MockedFunction<typeof fsPromises.readFile>;
+type MockedStatSyncFn = jest.MockedFunction<typeof fs.statSync>;
+type MockedAxiosGetFn = jest.MockedFunction<typeof axiosNs.default.get>;
+
+// --- Declare Mock Function Variables (assigned in beforeEach) ---
+// These will hold the mocked functions retrieved via jest.requireMock
+let mockReadFile: MockedReadFileFn;
+let mockStatSync: MockedStatSyncFn;
+let mockAxiosGet: MockedAxiosGetFn;
+
+// --- Import Module Under Test ---
+// Import after mocks are defined
+import { extractAssets } from '../../../src/core/extractor'; // Adjust path as needed
+
+// ================ TEST SETUP (Constants & Mock Data - Defined Globally) ================
+
+// Determine if running on Windows for path handling
 const isWindows = process.platform === 'win32';
-const mockBaseDir = path.resolve(isWindows ? 'C:\\mock\\base\\dir' : '/mock/base/dir');
-let tempMockBaseUrlFile = mockBaseDir.replace(/\\/g, '/');
-// Ensure correct file URL format
-if (isWindows && /^[A-Z]:\//i.test(tempMockBaseUrlFile)) {
-     tempMockBaseUrlFile = 'file:///' + tempMockBaseUrlFile;
-} else if (!tempMockBaseUrlFile.startsWith('/')) {
-    tempMockBaseUrlFile = '/' + tempMockBaseUrlFile; // Ensure leading slash for non-Windows absolute paths
-    tempMockBaseUrlFile = 'file://' + tempMockBaseUrlFile;
-} else {
-     tempMockBaseUrlFile = 'file://' + tempMockBaseUrlFile;
-}
-const mockBaseUrlFile = tempMockBaseUrlFile.endsWith('/') ? tempMockBaseUrlFile : tempMockBaseUrlFile + '/';
-const mockBaseUrlHttp = 'https://example.com/base/dir/';
-
-
-// --- Mock File Paths ---
-const styleCssPath = path.join(mockBaseDir, 'style.css');
-const scriptJsPath = path.join(mockBaseDir, 'script.js');
-const datauriCssPath = path.join(mockBaseDir, 'datauri.css');
-const deepCssPath = path.join(mockBaseDir, 'css', 'deep.css');
-const fontPath = path.join(mockBaseDir, 'font', 'relative-font.woff2');
-const bgImagePath = path.join(mockBaseDir, 'images', 'bg.png');
-const imagePath = path.join(mockBaseDir, 'image.png');
-const nestedImagePath = path.join(mockBaseDir, 'images', 'nested-img.png');
-const cycle1CssPath = path.join(mockBaseDir, 'cycle1.css');
-const cycle2CssPath = path.join(mockBaseDir, 'cycle2.css');
-const nonexistentPath = path.join(mockBaseDir, 'nonexistent.css');
-const unreadablePath = path.join(mockBaseDir, 'unreadable.css');
-const deepHtmlDirPath = path.join(mockBaseDir, 'pages', 'about');
-const unknownFilePath = path.join(mockBaseDir, 'file.other');
-const invalidUtf8CssPath = path.join(mockBaseDir, 'invalid-utf8.css');
-
-// === Test Helpers ===
-
-/** Helper to resolve file URLs */
-const getResolvedFileUrl = (relativePath: string): string => {
-    try { return new URL(relativePath.replace(/\\/g, '/'), mockBaseUrlFile).href; }
-    catch (e) { console.error(`TEST HELPER FAIL: getResolvedFileUrl failed for "<span class="math-inline">\{relativePath\}" with base "</span>{mockBaseUrlFile}": ${e}`); return `ERROR_RESOLVING_FILE_${relativePath}`; }
+// Define a mock base directory path based on OS
+const mockBaseDirPath = path.resolve(isWindows ? 'C:\\mock\\base\\dir' : '/mock/base/dir');
+// Create the corresponding file URL for the base directory
+const mockBaseFileUrl = pathToFileURL(mockBaseDirPath + path.sep).href; // Ensure trailing slash
+// Define a mock HTTP base URL
+const mockBaseHttpUrl = 'https://example.com/base/dir/';
+
+// Helper function to normalize paths for consistent comparisons
+const normalizePath = (filePath: string): string => path.normalize(filePath);
+
+// Define paths for various mock files used in tests
+const filePaths = {
+    styleCss: path.join(mockBaseDirPath, 'style.css'),
+    scriptJs: path.join(mockBaseDirPath, 'script.js'),
+    deepCss: path.join(mockBaseDirPath, 'css', 'deep.css'),
+    fontFile: path.join(mockBaseDirPath, 'font', 'font.woff2'),
+    bgImage: path.join(mockBaseDirPath, 'images', 'bg.png'),
+    nestedImage: path.join(mockBaseDirPath, 'images', 'nested-img.png'),
+    nonexistent: path.join(mockBaseDirPath, 'nonexistent.file'),
+    unreadable: path.join(mockBaseDirPath, 'unreadable.file'),
+    invalidUtf8: path.join(mockBaseDirPath, 'invalid-utf8.css'),
+    dataUriCss: path.join(mockBaseDirPath, 'data-uri.css'),
+    cycle1Css: path.join(mockBaseDirPath, 'cycle1.css'),
+    cycle2Css: path.join(mockBaseDirPath, 'cycle2.css'),
+    iterationStartCss: path.join(mockBaseDirPath, 'start.css'), // For loop test
+    complexUrlCss: path.join(mockBaseDirPath, 'complex-url.css'), // CSS containing URL with query/fragment
 };
-/** Helper to resolve http URLs */
-const getResolvedHttpUrl = (relativePath: string): string => {
-    try { return new URL(relativePath, mockBaseUrlHttp).href; }
-    catch (e) { console.error(`TEST HELPER FAIL: getResolvedHttpUrl failed for "<span class="math-inline">\{relativePath\}" with base "</span>{mockBaseUrlHttp}": ${e}`); return `ERROR_RESOLVING_HTTP_${relativePath}`; }
-};
-/** Helper to convert file URL to path */
-const getNormalizedPathFromFileUrl = (fileUrl: string): string => {
-    try { return path.normalize(fileURLToPath(fileUrl)); }
-    catch (e) { console.error(`TEST HELPER FAIL: getNormalizedPathFromFileUrl failed for "${fileUrl}": ${e}`); return `ERROR_NORMALIZING_${fileUrl}`; }
-};
-
 
-// --- Define ExpectedAsset Type ---
-// This allows using Jest matchers for the 'content' property in tests without TS errors
-type ExpectedAsset = Omit<Partial<Asset>, 'content'> & {
-    url: string;
-    content?: any; // Using 'any' to allow Jest matchers like expect.stringContaining()
+// --- Mock Data ---
+// Buffer containing invalid UTF-8 sequence
+const invalidUtf8Buffer = Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x80, 0x6f]); // Contains 0x80 which is invalid in UTF-8
+
+// Map normalized file paths to their mock content (string or Buffer)
+const mockFileContents: Record<string, string | Buffer> = {
+    [normalizePath(filePaths.styleCss)]: '@import url("./css/deep.css");\nbody { background: url("images/bg.png"); @font-face { src: url("font/font.woff2"); } }',
+    [normalizePath(filePaths.scriptJs)]: 'console.log("mock script");',
+    [normalizePath(filePaths.deepCss)]: 'h1 { background: url("../images/nested-img.png"); }', // Contains nested relative path
+    [normalizePath(filePaths.fontFile)]: Buffer.from('mock-font-data'), // Binary data
+    [normalizePath(filePaths.bgImage)]: Buffer.from('mock-image-data'), // Binary data
+    [normalizePath(filePaths.nestedImage)]: Buffer.from('mock-nested-image-data'), // Binary data for nested image
+    [normalizePath(filePaths.invalidUtf8)]: invalidUtf8Buffer, // Invalid UTF-8 buffer
+    [normalizePath(filePaths.dataUriCss)]: 'body { background: url(data:image/png;base64,SHORT_DATA_URI); }', // CSS containing a data URI
+    [normalizePath(filePaths.cycle1Css)]: '@import url("cycle2.css");', // CSS for circular import test
+    [normalizePath(filePaths.cycle2Css)]: '@import url("cycle1.css");', // CSS for circular import test
+    [normalizePath(filePaths.iterationStartCss)]: '@import url("gen_1.css");', // Start file for iteration test
+    [normalizePath(filePaths.complexUrlCss)]: 'body { background: url("images/bg.png?v=123#section"); }', // CSS with query/fragment URL
+    [normalizePath(filePaths.unreadable)]: Buffer.from(''), // Empty buffer for the unreadable file (content doesn't matter, error is simulated)
+    // Note: nonexistent file doesn't need content, its absence is simulated by the mock
 };
 
+// --- Mock Directory/File Structure ---
+// Set of directories that should exist in the mock structure
+const mockDirs = new Set<string>(
+    [ mockBaseDirPath, path.dirname(filePaths.deepCss), path.dirname(filePaths.fontFile), path.dirname(filePaths.bgImage) ].map(normalizePath)
+);
+// Set of files that should exist in the mock structure (used by statSync mock)
+const mockFiles = new Set<string>(
+    // Get all keys (paths) from mockFileContents
+    Object.keys(mockFileContents)
+    // Add paths for files that should exist but might cause read errors
+    .concat([filePaths.unreadable].map(normalizePath))
+    // Note: filePaths.nonexistent is *not* added here, so statSync will fail for it
+);
+
+// --- Helpers ---
+// Helper to resolve URLs consistently within tests
+const resolveUrl = (relativePath: string, baseUrl: string): string => {
+    try { return new URL(relativePath, baseUrl).href; }
+    catch (e) { console.error(`Resolve URL error in test helper: ${relativePath} / ${baseUrl}`); return `ERROR_RESOLVING_${relativePath}`; }
+};
 
-/*
-* Custom Jest matcher helper with improved file URL matching.
-* Checks if actualAssets matches expectedAssets based on URL and other properties.
-* Uses flexible matching strategies for file URLs.
-* @param {Asset[]} actualAssets - The array returned by the function under test.
-* @param {ExpectedAsset[]} expectedAssets - Array of expected asset objects (URL required). Uses ExpectedAsset type.
-*/
-const expectAssetsToContain = (actualAssets: Asset[], expectedAssets: ExpectedAsset[]) => { // Use ExpectedAsset[] for the parameter
-     // Log the actual assets for debugging
-    console.log(`DEBUG: Actual Assets (${actualAssets.length}):`);
-    actualAssets.forEach((asset, i) => console.log(`  [${i}] <span class="math-inline">\{asset\.url\} \(</span>{asset.type}) ${asset.content ? `(${typeof asset.content}, ${asset.content.length} chars)` : '(no content)'}`));
-
-    console.log(`DEBUG: Expected Assets (${expectedAssets.length}):`); // Corrected variable name here
-    expectedAssets.forEach((asset, i) => console.log(`  [${i}] <span class="math-inline">\{asset\.url\} \(</span>{asset.type}) ${asset.content ? `(${typeof asset.content})` : '(no content)'}`)); // Corrected variable name here
-
-    const actualUrls = actualAssets.map(a => a.url);
-
-    expectedAssets.forEach(expected => { // Corrected variable name here
-        // Improved flexible matching for file URLs
-        let actualAsset: Asset | undefined;
-
-        if (expected.url.startsWith('file:')) {
-            // Strategy 1: Match by normalized file path
-            let expectedPath: string;
-            try {
-                expectedPath = fileURLToPath(expected.url);
-                expectedPath = path.normalize(expectedPath);
-            } catch (e) {
-                // Fallback if URL parsing fails (e.g., invalid characters)
-                console.warn(`[Test Helper Warning] Could not normalize expected file URL: ${expected.url}`);
-                expectedPath = expected.url; // Use original string for comparison
-            }
-
-            actualAsset = actualAssets.find(a => {
-                if (a.type !== expected.type) return false; // Check type first
-
-                let actualPath: string;
-                try {
-                    if (a.url.startsWith('file:')) {
-                        actualPath = fileURLToPath(a.url);
-                        actualPath = path.normalize(actualPath);
-                        return actualPath === expectedPath;
-                    }
-                } catch (e) {
-                    // If actual URL parsing fails, log and continue (won't match)
-                     console.warn(`[Test Helper Warning] Could not normalize actual file URL: ${a.url}`);
-                }
-                // If not a file URL or parsing failed, it won't match a file: expected path
-                return false;
-            });
-
-            // Strategy 2: Match by filename and type (if path match failed)
-            if (!actualAsset) {
-                const expectedFileName = expected.url.split('/').pop();
-                actualAsset = actualAssets.find(a =>
-                    a.type === expected.type &&
-                    a.url.split('/').pop() === expectedFileName
-                );
-                 if (actualAsset) console.log(`DEBUG: Matched ${expected.url} via filename strategy.`);
-            }
-
-            // Strategy 3: Match by path fragment (if filename match failed)
-            if (!actualAsset) {
-                const expectedPathFragment = expected.url.split('/').slice(-2).join('/');
-                actualAsset = actualAssets.find(a =>
-                    a.type === expected.type &&
-                    a.url.includes(expectedPathFragment)
-                );
-                 if (actualAsset) console.log(`DEBUG: Matched ${expected.url} via path fragment strategy.`);
-            }
-        } else {
-            // For non-file URLs, use exact matching (or consider case-insensitivity if needed)
-            actualAsset = actualAssets.find(a => a.url === expected.url && a.type === expected.type);
-        }
-
-        // Debug logging for asset not found
-        if (!actualAsset) {
-            console.error(`\n`);
-            console.error(`!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!`);
-            console.error(`[Test Failure Debug] Asset not found in actual results!`);
-            console.error(`  => Expected URL: ${expected.url}`);
-            console.error(`  => Expected Type: ${expected.type ?? '(any)'}`);
-            console.error(`  => Actual Assets Received (${actualAssets.length}):`);
-            actualAssets.forEach((a, i) => console.error(`     [${i}]: <span class="math-inline">\{a\.url\} \(</span>{a.type})`));
-            console.error(`!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!`);
-            console.error(`\n`);
-        }
-
-        expect(actualAsset).toBeDefined(); // Assert that the asset was found
-
-        if (!actualAsset) return; // Skip further checks if asset wasn't found
-
-        // Always check type (already done in find, but good practice)
-         expect(actualAsset.type).toBe(expected.type);
-
-        // Check content if specified in the expected asset
-        if (Object.prototype.hasOwnProperty.call(expected, 'content')) {
-            const { content: expectedContent } = expected;
-
-            // Check if the expected content is a Jest asymmetric matcher
-            const isAsymmetricMatcher = typeof expectedContent === 'object' &&
-                                        expectedContent !== null &&
-                                        typeof (expectedContent as any).asymmetricMatch === 'function';
-
-            if (isAsymmetricMatcher) {
-                // Use toEqual for asymmetric matchers
-                expect(actualAsset.content).toEqual(expectedContent);
-            } else {
-                // Use toBe for exact value comparison (including undefined)
-                expect(actualAsset.content).toBe(expectedContent);
-            }
+// Type definition for expected asset structure in assertions
+type ExpectedAsset = { type: Asset['type']; url: string; content?: any; };
+
+// Helper function to assert that the actual assets contain the expected assets
+function expectAssetsToContain(actualAssets: Asset[], expectedAssets: ExpectedAsset[]): void {
+    // Check if the number of found assets matches the expected number
+    expect(actualAssets).toHaveLength(expectedAssets.length);
+    // Check each expected asset
+    expectedAssets.forEach(expected => {
+        // Find the corresponding asset in the actual results by type and URL
+        const found = actualAssets.find(asset => asset.type === expected.type && asset.url === expected.url);
+        // Assert that the asset was found
+        expect(found).toBeDefined();
+        // If content is expected, assert that it matches (using toEqual for deep comparison if needed)
+        if (found && expected.content !== undefined) {
+            expect(found.content).toEqual(expected.content);
         }
     });
-};
-// =================== THE TESTS! ===================
-describe('🔍 extractAssets() - Round 8! FIGHT!', () => { // Incremented round for fun
-
-    let mockLogger: Logger;
-    let mockLoggerWarnSpy: jest.SpiedFunction<typeof mockLogger.warn>;
-    let mockLoggerErrorSpy: jest.SpiedFunction<typeof mockLogger.error>;
-    let mockLoggerDebugSpy: jest.SpiedFunction<typeof mockLogger.debug>;
-    let mockLoggerInfoSpy: jest.SpiedFunction<typeof mockLogger.info>;
-
-    // Example buffer for invalid UTF-8 data
-    const invalidUtf8Buffer = Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x80, 0x6f]); // "Hell\x80o"
-
-   /** Sets up default mock implementations with improved path handling */
-    const setupDefaultMocks = () => {
-        // --- Mock fs.readFile ---
-        mockedReadFile.mockImplementation(async (fileUrlOrPath): Promise<Buffer> => {
-            let filePath: string = '';
-
-             // Normalize the incoming path or URL to a consistent format
-             try {
-                 if (typeof fileUrlOrPath === 'string') {
-                     filePath = fileUrlOrPath.startsWith('file:') ? fileURLToPath(fileUrlOrPath) : fileUrlOrPath;
-                 } else if (fileUrlOrPath instanceof URL && fileUrlOrPath.protocol === 'file:') {
-                     filePath = fileURLToPath(fileUrlOrPath);
-                 } else if (typeof (fileUrlOrPath as any)?.path === 'string') { // Handle FileHandle-like objects if used
-                     filePath = (fileUrlOrPath as any).path;
-                 } else {
-                     // Handle Buffer input if fs.readFile is called with a Buffer path (less common)
-                     if (Buffer.isBuffer(fileUrlOrPath)) {
-                         filePath = fileUrlOrPath.toString(); // Assume UTF-8 path string
-                         if (filePath.startsWith('file:')) {
-                            filePath = fileURLToPath(filePath);
-                         }
-                     } else {
-                        throw new Error(`[Mock readFile] Unsupported input type: ${typeof fileUrlOrPath}`);
-                     }
-                 }
-             } catch (e: any) {
-                  console.error(`[Mock readFile Error] Failed to convert input to path: ${String(fileUrlOrPath)}`, e);
-                  const err = new Error(`[Mock readFile Error] Failed to convert input to path: ${e.message}`) as NodeJS.ErrnoException;
-                  err.code = 'EINVAL'; // Indicate invalid argument
-                  throw err;
-             }
-
+}
 
-            if (!filePath) {
-                 console.error("[Mock readFile Error] Could not determine file path from input:", fileUrlOrPath);
-                const err = new Error('Invalid file path provided to mock readFile') as NodeJS.ErrnoException;
-                err.code = 'EINVAL';
-                throw err;
-            }
+// Interface for Node.js errors with a 'code' property
+interface NodeJSErrnoException extends Error { code?: string; }
+// Interface to represent an Axios error structure for mocking
+interface MockAxiosError extends AxiosError { isAxiosError: true; }
+
+
+// ================ MOCK IMPLEMENTATIONS (Defined Globally) ================
+
+// Mock implementation for fsPromises.readFile
+const readFileMockImplementation = async (
+    filePathArg: PathLike | FileHandle,
+    options?: BufferEncoding | (({ encoding?: null; flag?: OpenMode; } & AbortSignal)) | null // Match fsPromises.readFile signature
+): Promise<Buffer | string> => {
+    let normalizedPath: string = '';
+     try {
+         // Normalize the input path regardless of whether it's a string, URL, Buffer, or FileHandle
+         if (filePathArg instanceof URL) { normalizedPath = normalizePath(fileURLToPath(filePathArg)); }
+         else if (typeof filePathArg === 'string') { normalizedPath = normalizePath(filePathArg.startsWith('file:') ? fileURLToPath(filePathArg) : filePathArg); }
+         else if (Buffer.isBuffer(filePathArg)) { normalizedPath = normalizePath(filePathArg.toString()); }
+         // Rudimentary check for FileHandle-like object (adjust if using actual FileHandles)
+         else if (typeof (filePathArg as any)?.read === 'function') { normalizedPath = normalizePath((filePathArg as any).path || String(filePathArg)); }
+         else { throw new Error('Unsupported readFile input type in mock'); }
+     } catch(e) { console.error("Error normalizing path in readFile mock:", filePathArg, e); throw e; }
+
+    // console.log(`[DEBUG mockReadFileFn] Requesting normalized path: "${normalizedPath}"`); // Optional debug
+
+    // Simulate ENOENT (file not found) error
+    if (normalizedPath === normalizePath(filePaths.nonexistent)) { const error: NodeJSErrnoException = new Error(`ENOENT: no such file or directory, open '${normalizedPath}'`); error.code = 'ENOENT'; throw error; }
+    // Simulate EACCES (permission denied) error
+    if (normalizedPath === normalizePath(filePaths.unreadable)) { const error: NodeJSErrnoException = new Error(`EACCES: permission denied, open '${normalizedPath}'`); error.code = 'EACCES'; throw error; }
+
+    // Retrieve mock content based on the normalized path
+    const content = mockFileContents[normalizedPath];
+    if (content !== undefined) {
+        // console.log(`[DEBUG mockReadFileFn] FOUND content for: "${normalizedPath}".`); // Optional debug
+        // Always return a Buffer, as the actual readFile would
+        return Buffer.isBuffer(content) ? content : Buffer.from(content);
+    }
+
+    // If content not found in mock map, simulate ENOENT
+    // console.log(`[DEBUG mockReadFileFn] NOT FOUND content for: "${normalizedPath}". Available keys: ${Object.keys(mockFileContents).join(', ')}`); // Optional debug
+    const error: NodeJSErrnoException = new Error(`ENOENT (Mock): Content not found for ${normalizedPath}`); error.code = 'ENOENT'; throw error;
+};
 
-            // Normalize path for consistent comparison
-            const normalizedPath = path.normalize(filePath);
+// Mock implementation for fs.statSync
+const statSyncMockImplementation = (
+    pathToCheck: PathLike,
+    options?: StatSyncOptions & { bigint?: false; throwIfNoEntry?: boolean } | { bigint: true; throwIfNoEntry?: boolean } // Match fs.statSync signature
+): Stats | BigIntStats | undefined => {
+    let normalizedPath: string = '';
+     try {
+         // Normalize the input path
+         if (pathToCheck instanceof URL) { normalizedPath = normalizePath(fileURLToPath(pathToCheck)); }
+         else if (typeof pathToCheck === 'string') { normalizedPath = normalizePath(pathToCheck.startsWith('file:') ? fileURLToPath(pathToCheck) : pathToCheck); }
+         else if (Buffer.isBuffer(pathToCheck)) { normalizedPath = normalizePath(pathToCheck.toString()); }
+         else { throw new Error(`Unsupported statSync input type in mock: ${typeof pathToCheck}`); }
+     } catch(e) {
+         console.error("Error normalizing path in statSync mock:", pathToCheck, e);
+         // Handle throwIfNoEntry option if normalization fails
+         if (options?.throwIfNoEntry === false) { return undefined; }
+         throw e; // Re-throw normalization error if throwIfNoEntry is not false
+     }
+
+    // Helper to create a mock Stats or BigIntStats object
+    const createStats = (isFile: boolean): Stats | BigIntStats => {
+        // Base properties common to both Stats and BigIntStats
+        const baseProps = {
+            dev: 0, ino: 0, mode: isFile ? 33188 : 16877, /* file vs dir mode */ nlink: 1, uid: 0, gid: 0, rdev: 0,
+            blksize: 4096, blocks: 8,
+            atimeMs: Date.now(), mtimeMs: Date.now(), ctimeMs: Date.now(), birthtimeMs: Date.now(),
+            atime: new Date(), mtime: new Date(), ctime: new Date(), birthtime: new Date(),
+            isFile: () => isFile, isDirectory: () => !isFile,
+            isBlockDevice: () => false, isCharacterDevice: () => false,
+            isSymbolicLink: () => false, isFIFO: () => false, isSocket: () => false,
+            // Calculate size based on mock content or default
+            size: isFile ? (mockFileContents[normalizedPath]?.length ?? 100) : 4096
+        };
 
-            // Define the content map with proper mock content for all expected files
-            const contentMap: Record<string, string | Buffer> = {
-                [path.normalize(styleCssPath)]: `@import url("./css/deep.css");
-    body {
-        background: url("images/bg.png");
-        font-family: "CustomFont", sans-serif;
-        /* Example of font definition */
-        @font-face {
-          font-family: 'MyWebFont';
-          src: url('font/relative-font.woff2') format('woff2');
-          font-weight: 600;
-          font-style: normal;
+        // If bigint option is true, return a BigIntStats-compatible object
+        if (options?.bigint) {
+            return {
+                isFile: baseProps.isFile, isDirectory: baseProps.isDirectory,
+                isBlockDevice: baseProps.isBlockDevice, isCharacterDevice: baseProps.isCharacterDevice,
+                isSymbolicLink: baseProps.isSymbolicLink, isFIFO: baseProps.isFIFO, isSocket: baseProps.isSocket,
+                atime: baseProps.atime, mtime: baseProps.mtime, ctime: baseProps.ctime, birthtime: baseProps.birthtime,
+                dev: BigInt(baseProps.dev), ino: BigInt(baseProps.ino), mode: BigInt(baseProps.mode), nlink: BigInt(baseProps.nlink), uid: BigInt(baseProps.uid), gid: BigInt(baseProps.gid), rdev: BigInt(baseProps.rdev),
+                blksize: BigInt(baseProps.blksize), blocks: BigInt(baseProps.blocks), size: BigInt(baseProps.size),
+                // Convert milliseconds to nanoseconds BigInt
+                atimeNs: BigInt(Math.floor(baseProps.atimeMs * 1e6)),
+                mtimeNs: BigInt(Math.floor(baseProps.mtimeMs * 1e6)),
+                ctimeNs: BigInt(Math.floor(baseProps.ctimeMs * 1e6)),
+                birthtimeNs: BigInt(Math.floor(baseProps.birthtimeMs * 1e6)),
+            } as BigIntStats; // Cast to satisfy the type
         }
-    }`, // Added @font-face example
-                [path.normalize(scriptJsPath)]: `console.log("mock script");`,
-                [path.normalize(datauriCssPath)]: `body {
-        background: url("image.png");
-        background-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjwvc3ZnPg==');
-    }`,
-                [path.normalize(deepCssPath)]: `h1 {
-        background: url("../images/nested-img.png"); /* Relative path from deep.css */
-        color: blue;
-    }`,
-                [path.normalize(fontPath)]: Buffer.from('mock-woff2-font-data-for-mywebfont'), // Make font data unique if needed
-                [path.normalize(bgImagePath)]: Buffer.from('mock-png-bg-data-abcdef'), // Make image data unique
-                [path.normalize(imagePath)]: Buffer.from('mock-png-data-image-12345'), // Make image data unique
-                [path.normalize(nestedImagePath)]: Buffer.from('mock-png-nested-img-data-xyz'), // Make image data unique
-                [path.normalize(cycle1CssPath)]: `@import url("cycle2.css");`,
-                [path.normalize(cycle2CssPath)]: `@import url("cycle1.css");`,
-                [path.normalize(invalidUtf8CssPath)]: invalidUtf8Buffer,
-                [path.normalize(unknownFilePath)]: invalidUtf8Buffer, // For the 'other' type test
-            };
-
-            // Specific error cases
-            if (normalizedPath === path.normalize(nonexistentPath)) {
-                const err = new Error(`ENOENT: no such file or directory, open '${normalizedPath}'`) as NodeJS.ErrnoException;
-                err.code = 'ENOENT';
-                throw err;
-            }
-
-            if (normalizedPath === path.normalize(unreadablePath)) {
-                const err = new Error(`EACCES: permission denied, open '${normalizedPath}'`) as NodeJS.ErrnoException;
-                err.code = 'EACCES';
-                throw err;
-            }
-
-            // Loop detection for the "iteration limit" test
-            if (normalizedPath.includes('generated_')) {
-                const match = normalizedPath.match(/generated_(\d+)\.css$/);
-                const counter = match ? parseInt(match[1], 10) : 0;
-                 if (counter >= 1005) { // Prevent infinite loop in mock itself
-                      console.warn(`[Mock readFile Warning] Stopping generation for limit test at ${counter}`);
-                      return Buffer.from(`/* Limit Reached in Mock */`);
-                 }
-                const nextUniqueRelativeUrl = `generated_${counter + 1}.css`;
-                return Buffer.from(`@import url("${nextUniqueRelativeUrl}"); /* Cycle ${normalizedPath} */`);
-            }
-
-            // Return the mapped content or a fallback/error
-            const content = contentMap[normalizedPath];
-            if (content !== undefined) {
-                return Buffer.isBuffer(content) ? content : Buffer.from(content);
-            } else {
-                // If the file wasn't explicitly mapped, treat it as non-existent for tests
-                console.warn(`[Test Mock Warning] fs.readFile mock throwing ENOENT for unmapped path: ${normalizedPath}`);
-                const err = new Error(`ENOENT: no such file or directory, open '${normalizedPath}' (unmapped in test mock)`) as NodeJS.ErrnoException;
-                err.code = 'ENOENT';
-                throw err;
-                // Alternatively, return default content if some tests expect reads for other files:
-                // console.warn(`[Test Mock Warning] fs.readFile mock returning default content for unexpected path: ${normalizedPath}`);
-                // return Buffer.from(`/* Default Mock Content for: ${normalizedPath} */`);
-            }
-        });
-
-        // --- Mock axios.get ---
-        mockedAxiosGet.mockImplementation(async (url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<Buffer>> => {
-            const { AxiosHeaders } = axiosNs; // Ensure AxiosHeaders is accessible
-            let dataBuffer = Buffer.from(`/* Mock HTTP Response: ${url} */`);
-            let contentType = 'text/plain';
-            let status = 200;
-            let statusText = 'OK';
-            const responseHeaders = new AxiosHeaders();
+        // Otherwise, return a standard Stats-compatible object
+        return baseProps as Stats;
+    };
 
-            // Helper to safely create header record for config
-             const createSafeHeaderRecord = (h: any): Record<string, AxiosHeaderValue> => {
-                 const hr: Record<string, AxiosHeaderValue> = {};
-                 if (h) {
-                     for (const k in h) {
-                         if (Object.prototype.hasOwnProperty.call(h, k)) {
-                             const v = h[k];
-                             // Ensure header values are primitives or arrays of primitives
-                             if (v !== undefined && v !== null && (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || Array.isArray(v))) {
-                                 hr[k] = v as AxiosHeaderValue;
-                             } else if (v !== undefined && v !== null) {
-                                console.warn(`[Mock Axios Header Warning] Skipping non-primitive header value for key "${k}":`, v);
-                             }
-                         }
-                     }
-                 }
-                 return hr;
-             };
+    // Check if the normalized path represents a mocked directory
+    if (mockDirs.has(normalizedPath)) { return createStats(false); } // It's a directory
+    // Check if the normalized path represents a mocked file (or generated file in loop test)
+    if (mockFiles.has(normalizedPath) || path.basename(normalizedPath).startsWith('gen_')) { return createStats(true); } // It's a file
 
-            const requestConfigHeaders = new AxiosHeaders(createSafeHeaderRecord(config?.headers));
+    // Path not found in mocks
+    if (options?.throwIfNoEntry === false) { return undefined; } // Return undefined if not throwing
+    // Throw ENOENT error if path not found and not suppressed
+    const error: NodeJSErrnoException = new Error(`ENOENT (Mock): statSync path not found: ${normalizedPath}`); error.code = 'ENOENT'; throw error;
+};
 
-            // Simulate different responses based on URL
-            if (url.includes('fail.net') || url.includes('timeout.net')) {
-                status = url.includes('fail.net') ? 500 : 408;
-                statusText = url.includes('fail.net') ? 'Internal Server Error' : 'Request Timeout';
-                const e = new Error(`Mock ${status} for ${url}`) as AxiosError<Buffer>;
-                const cfg: InternalAxiosRequestConfig = {
-                    ...(config ?? {}),
-                    headers: requestConfigHeaders, // Use the created AxiosHeaders object
-                    url: url,
-                    method: 'get'
-                };
-                e.config = cfg;
-                e.response = {
-                    data: Buffer.from(statusText),
-                    status,
-                    statusText,
-                    headers: new AxiosHeaders(), // Use AxiosHeaders for response too
-                    config: cfg
-                };
-                e.request = {}; // Mock request object
-                e.isAxiosError = true; // Crucial for axios error handling
-                 if (url.includes('timeout.net')) {
-                      e.code = 'ECONNABORTED'; // Simulate timeout code
-                      e.message = `timeout of ${config?.timeout ?? 10000}ms exceeded`; // Simulate timeout message
+// Mock implementation for axios.get
+const axiosGetMockImplementation = async (
+    url: string,
+    config?: AxiosRequestConfig // Match axios.get signature
+): Promise<AxiosResponse<Buffer>> => { // Return Buffer data
+    // console.log(`[DEBUG mockAxiosGet] Requesting URL: "${url}"`); // Optional debug
+
+    const { AxiosHeaders } = axiosNs; // Use the AxiosHeaders class from the namespace
+    let dataBuffer: Buffer; // Content will be a Buffer
+    let contentType = 'text/plain'; // Default content type
+    let status = 200; // Default success status
+    let statusText = 'OK'; // Default success status text
+
+    // Helper to create mock Axios request headers
+    const getRequestHeaders = (reqConfig?: AxiosRequestConfig): AxiosRequestHeaders => {
+        const headers = new AxiosHeaders(); // Instantiate AxiosHeaders
+        if (reqConfig?.headers) {
+            // Copy headers from config if provided
+            for (const key in reqConfig.headers) {
+                 if (Object.prototype.hasOwnProperty.call(reqConfig.headers, key)) {
+                      // Use AxiosHeaders methods for setting headers
+                      headers.set(key, reqConfig.headers[key] as AxiosHeaderValue);
                  }
-                throw e; // Throw the mocked Axios error
-            } else if (url.includes('style.css')) { // e.g., https://example.com/styles/style.css
-                contentType = 'text/css';
-                dataBuffer = Buffer.from(`body { background: url("/img/remote-bg.jpg?v=1"); color: red; } /* Remote CSS */`);
-            } else if (url.includes('script.js')) { // e.g., https://okay.net/script.js
-                contentType = 'application/javascript';
-                dataBuffer = Buffer.from(`console.log('remote script');`);
-            } else if (url.includes('logo.png')) { // e.g., https://example.com/images/logo.png
-                contentType = 'image/png';
-                dataBuffer = Buffer.from('mock-remote-png-logo-data-abc'); // Unique data
-            } else if (url.includes('remote-bg.jpg')) { // e.g., https://example.com/img/remote-bg.jpg?v=1
-                contentType = 'image/jpeg';
-                dataBuffer = Buffer.from('mock-remote-jpg-bg-data-def'); // Unique data
             }
-             // Add more cases as needed for other remote URLs in tests
-
-            responseHeaders.set('content-type', contentType);
-            const responseConfig: InternalAxiosRequestConfig = {
-                 ...(config ?? {}),
-                 headers: requestConfigHeaders, // Use the created AxiosHeaders object
-                 url: url,
-                 method: 'get'
-            };
+        }
+        return headers;
+    };
+    // Helper to create mock InternalAxiosRequestConfig
+    const createInternalConfig = (reqConfig?: AxiosRequestConfig): InternalAxiosRequestConfig => {
+        const requestHeaders = getRequestHeaders(reqConfig);
+        // Construct the config object, ensuring headers is an AxiosHeaders instance
+        // Need to satisfy the complex InternalAxiosRequestConfig type
+        const internalConfig: InternalAxiosRequestConfig = {
+             url: url,
+             method: 'get',
+             ...(reqConfig || {}), // Spread original config
+             headers: requestHeaders, // Overwrite headers with AxiosHeaders instance
+             // Add other potentially required fields with default values if needed
+             // baseURL: reqConfig?.baseURL || '',
+             // params: reqConfig?.params || {},
+             // data: reqConfig?.data,
+             // timeout: reqConfig?.timeout || 0,
+             // responseType: reqConfig?.responseType || 'json',
+             // ... add others based on Axios version and usage ...
+        };
+        return internalConfig;
+    };
 
-            const mockResponse: AxiosResponse<Buffer> = {
-                data: dataBuffer,
+    // Simulate errors based on URL content
+    if (url.includes('error')) { status = 404; statusText = 'Not Found'; }
+    // Simulate timeout using status code 408 and setting error code later
+    if (url.includes('timeout')) { status = 408; statusText = 'Request Timeout'; }
+
+    // If simulating an error status
+    if (status !== 200) {
+        const errorConfig = createInternalConfig(config);
+        // *** Create a plain object that mimics AxiosError ***
+        const error: any = { // Use 'any' for flexibility in mock creation
+            // Base Error properties (optional but good practice)
+            name: 'Error', // Keep it generic or 'AxiosError'
+            message: status === 404 ? `Request failed with status code 404` : `Timeout of ${config?.timeout || 'unknown'}ms exceeded`,
+            stack: (new Error()).stack, // Capture a stack trace
+
+            // AxiosError specific properties
+            isAxiosError: true, // Explicitly set the flag Axios checks
+            code: status === 408 ? 'ECONNABORTED' : undefined, // Set code correctly
+            config: errorConfig, // Attach the config
+            request: {}, // Mock request object if needed
+            response: { // Attach the mock response
                 status,
                 statusText,
-                headers: responseHeaders, // Use AxiosHeaders instance
-                config: responseConfig, // Use the internal config type
-                request: {} // Mock request object
-            };
-
-            return Promise.resolve(mockResponse);
-        });
-
-        // --- Mock fs.statSync --- (improved path handling)
-        mockedStatSync.mockImplementation((p: fs.PathLike, options?: StatSyncOptions | undefined): fs.Stats => {
-            let mockPath: string;
-            try {
-                 // Handle URL objects, strings, and Buffers robustly
-                if (p instanceof URL) {
-                    mockPath = fileURLToPath(p);
-                } else if (typeof p === 'string') {
-                     // If it's already a file URL, convert it
-                     mockPath = p.startsWith('file:') ? fileURLToPath(p) : p;
-                } else if (Buffer.isBuffer(p)) {
-                     mockPath = p.toString(); // Assume UTF-8 path
-                     if (mockPath.startsWith('file:')) {
-                        mockPath = fileURLToPath(mockPath);
-                     }
-                }
-                 else {
-                     throw new Error(`Unsupported path type: ${typeof p}`);
-                 }
-                mockPath = path.normalize(mockPath); // Normalize after determining the path string
-            } catch (e: any) {
-                console.error(`[Mock statSync Error] Failed to convert path: ${String(p)}`, e);
-                const err = new Error(`ENOENT: invalid path for stat, stat '${String(p)}'. ${e.message}`) as NodeJS.ErrnoException;
-                err.code = 'ENOENT'; // Or potentially 'EINVAL' depending on error
-                 if (options?.throwIfNoEntry === false) return undefined as unknown as fs.Stats; // Handle option
-                throw err;
-            }
-
-            // Define known directories and files using normalized paths
-             const dirPaths = new Set([
-                 mockBaseDir,
-                 path.join(mockBaseDir, 'css'),
-                 path.join(mockBaseDir, 'font'),
-                 path.join(mockBaseDir, 'images'),
-                 deepHtmlDirPath // directory containing the deep HTML file
-             ].map(d => path.normalize(d)));
-
-             const filePaths = new Set([
-                 styleCssPath, scriptJsPath, datauriCssPath, deepCssPath,
-                 fontPath, bgImagePath, imagePath, nestedImagePath,
-                 cycle1CssPath, cycle2CssPath, nonexistentPath, unreadablePath,
-                 unknownFilePath, invalidUtf8CssPath
-             ].map(f => path.normalize(f)));
-
-             // Handle dynamically generated files for the limit test
-             if (mockPath.includes('generated_')) {
-                  // Assume these are files for the purpose of the test
-                 return { isDirectory: () => false, isFile: () => true } as fs.Stats;
-             }
-
+                data: Buffer.from(statusText), // Mock data
+                headers: new AxiosHeaders(),
+                config: errorConfig
+            },
+            // Add a basic toJSON if needed by any code consuming the error
+            toJSON: function () { return { message: this.message, code: this.code }; }
+        };
+        // console.log(`[DEBUG mockAxiosGet] Simulating ERROR object:`, error); // Optional debug
+        throw error; // Throw the simulated error object
+    }
+
+    // Simulate successful responses with appropriate content and type based on URL
+    if (url.includes('/styles/main.css')) { dataBuffer = Buffer.from('body { background: url("/images/remote-bg.jpg"); }'); contentType = 'text/css'; }
+    else if (url.includes('/js/script.js')) { dataBuffer = Buffer.from('console.log("remote script");'); contentType = 'application/javascript'; }
+    else if (url.includes('/js/lib.js')) { dataBuffer = Buffer.from('console.log("remote lib");'); contentType = 'application/javascript'; } // Handle protocol-relative case
+    else if (url.includes('/images/remote-bg.jpg')) { dataBuffer = Buffer.from('mock-remote-image-data'); contentType = 'image/jpeg'; }
+    else { dataBuffer = Buffer.from(`Mock content for ${url}`); } // Default fallback content
+
+    // Create mock response configuration and headers
+    const responseConfig = createInternalConfig(config);
+    const responseHeaders = new AxiosHeaders({ 'content-type': contentType }); // Use AxiosHeaders
+
+    // console.log(`[DEBUG mockAxiosGet] Simulating SUCCESS for URL: "${url}", ContentType: ${contentType}`); // Optional debug
+    // Return the successful AxiosResponse object
+    return {
+        data: dataBuffer, // Data as Buffer
+        status: 200,
+        statusText: 'OK',
+        headers: responseHeaders, // AxiosHeaders object
+        config: responseConfig, // InternalAxiosRequestConfig object
+        request: {} // Mock request object (can be empty or more detailed if needed)
+    };
+};
 
-            if (dirPaths.has(mockPath)) {
-                return { isDirectory: () => true, isFile: () => false } as fs.Stats;
-            }
 
-            if (filePaths.has(mockPath)) {
-                 // For the nonexistentPath, statSync should throw ENOENT *unless* throwIfNoEntry is false
-                if (mockPath === path.normalize(nonexistentPath) && options?.throwIfNoEntry !== false) {
-                     const err = new Error(`ENOENT: no such file or directory, stat '${mockPath}'`) as NodeJS.ErrnoException;
-                     err.code = 'ENOENT';
-                     throw err;
-                 }
-                // For all other known files (including nonexistent if throwIfNoEntry is false), return file stats
-                return { isDirectory: () => false, isFile: () => true } as fs.Stats;
-            }
-
-            // If path is not recognized, throw ENOENT unless throwIfNoEntry is false
-            if (options?.throwIfNoEntry === false) {
-                 return undefined as unknown as fs.Stats;
-            } else {
-                console.warn(`[Test Mock Warning] fs.statSync mock throwing ENOENT for unrecognized path: ${mockPath}`);
-                const err = new Error(`ENOENT: no such file or directory, stat '${mockPath}' (unmapped in test mock)`) as NodeJS.ErrnoException;
-                err.code = 'ENOENT';
-                throw err;
-            }
-        });
-    };
+// ================ TESTS ================
 
+describe('extractAssets', () => {
+    // Declare variables for logger and its spies
+    let mockLogger: Logger;
+    let mockLoggerWarnSpy: jest.SpiedFunction<typeof mockLogger.warn>;
+    let mockLoggerErrorSpy: jest.SpiedFunction<typeof mockLogger.error>;
 
     beforeEach(() => {
-        // Use desired log level for testing
-        mockLogger = new Logger(LogLevel.WARN); // Use DEBUG to see more logs during test runs
-
-        // Spy on logger methods
-        mockLoggerDebugSpy = jest.spyOn(mockLogger, 'debug');
+        // --- Retrieve Mocked Functions from Modules ---
+        // Use jest.requireMock to get the mocked versions of the modules
+        // Cast to the specific mocked function type for type safety
+        const fsPromisesMock = jest.requireMock('fs/promises') as typeof fsPromises;
+        mockReadFile = fsPromisesMock.readFile as MockedReadFileFn;
+        const fsMock = jest.requireMock('fs') as typeof fs;
+        mockStatSync = fsMock.statSync as MockedStatSyncFn;
+        const axiosMock = jest.requireMock('axios') as typeof axiosNs;
+        mockAxiosGet = axiosMock.default.get as MockedAxiosGetFn;
+
+        // --- Setup Logger and Spies ---
+        // Create a new Logger instance for each test (set level low for debugging if needed)
+        mockLogger = new Logger(LogLevel.WARN); // Or LogLevel.DEBUG
+        // Spy on the warn and error methods of this logger instance
         mockLoggerWarnSpy = jest.spyOn(mockLogger, 'warn');
         mockLoggerErrorSpy = jest.spyOn(mockLogger, 'error');
-        mockLoggerInfoSpy = jest.spyOn(mockLogger, 'info');
 
-        // Clear mocks and setup defaults before each test
-        mockReadFileFn.mockClear();
-        mockAxiosGetFn.mockClear();
-        mockedStatSync.mockClear();
-        setupDefaultMocks();
+        // --- Assign Mock Implementations ---
+        // Set the implementation for the mocked functions for this test run
+        // Use 'as any' to bypass strict type checking
+        mockReadFile.mockImplementation(readFileMockImplementation as any);
+        mockStatSync.mockImplementation(statSyncMockImplementation as any);
+        mockAxiosGet.mockImplementation(axiosGetMockImplementation as any);
     });
 
     afterEach(() => {
-        jest.restoreAllMocks(); // Restore original implementations
+        // Clear mock calls and reset implementations between tests
+        jest.clearAllMocks();
+        // Restore original implementations spied on with jest.spyOn (like the logger spies)
+        jest.restoreAllMocks();
     });
 
+    // ================ Test Cases ================
 
-    // === Core Functionality Tests ===
-
-    // it('✅ embeds content when embedAssets = true', async () => {
-    //     const parsed: ParsedHTML = { htmlContent: `<link href="style.css"><script src="script.js"></script>`, assets: [ { type: 'css', url: 'style.css' }, { type: 'js', url: 'script.js' } ] };
-    //     const result = await extractAssets(parsed, true, mockBaseDir, mockLogger);
-
-    //     // Use ExpectedAsset[] for the expected array
-    //     const assets: ExpectedAsset[] = [
-    //         { url: getResolvedFileUrl('style.css'), type: 'css', content: expect.stringContaining('@import') },
-    //         { url: getResolvedFileUrl('script.js'), type: 'js', content: 'console.log("mock script");' },
-    //         { url: getResolvedFileUrl('css/deep.css'), type: 'css', content: expect.stringContaining('../images/nested-img.png') }, // Asset from @import
-    //         { url: getResolvedFileUrl('font/relative-font.woff2'), type: 'font', content: expect.stringMatching(/^data:font\/woff2;base64,/) }, // Asset from url() in style.css -> @font-face
-    //         { url: getResolvedFileUrl('images/bg.png'), type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) }, // Asset from url() in style.css
-    //         { url: getResolvedFileUrl('images/nested-img.png'), type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) }, // Asset from url() in deep.css
-    //     ];
-    //     const sortedExpected = [...assets].sort((a, b) => a.url.localeCompare(b.url));
-    //     const sortedActual = [...result.assets].sort((a, b) => a.url.localeCompare(b.url));
-
-    //     expectAssetsToContain(sortedActual, sortedExpected);
-    //     // Expect reads for: style.css, deep.css, bg.png, relative-font.woff2, nested-img.png, script.js
-    //     expect(mockedReadFile).toHaveBeenCalledTimes(6);
-    //     expect(mockedStatSync).toHaveBeenCalledWith(mockBaseDir); // Initial base dir check
-    //     // Optionally check statSync for specific files/dirs if needed
-    // });
-
-    // it('🚫 skips embedding but discovers nested when embedAssets = false', async () => {
-    //     const parsed: ParsedHTML = { htmlContent: `<link href="style.css">`, assets: [{ type: 'css', url: 'style.css' }] };
-    //     const result = await extractAssets(parsed, false, mockBaseDir, mockLogger); // embedAssets = false
-
-    //     // Only style.css should be read to find nested assets
-    //     expect(mockedReadFile).toHaveBeenCalledTimes(1);
-    //     expect(mockedReadFile).toHaveBeenCalledWith(expect.stringContaining(styleCssPath)); // Or use normalized path check
-    //     expect(mockedStatSync).toHaveBeenCalledWith(mockBaseDir);
-
-    //     // Expected assets: initial CSS + discovered nested ones, all with undefined content
-    //     const assets: ExpectedAsset[] = [
-    //         { url: getResolvedFileUrl('style.css'), type: 'css', content: undefined },
-    //         { url: getResolvedFileUrl('css/deep.css'), type: 'css', content: undefined },        // Discovered via @import
-    //         { url: getResolvedFileUrl('font/relative-font.woff2'), type: 'font', content: undefined }, // Discovered via url()
-    //         { url: getResolvedFileUrl('images/bg.png'), type: 'image', content: undefined },    // Discovered via url()
-    //          { url: getResolvedFileUrl('images/nested-img.png'), type: 'image', content: undefined } // Discovered via url() in deep.css
-    //     ];
-    //     const sortedExpected = [...assets].sort((a, b) => a.url.localeCompare(b.url));
-    //     const sortedActual = [...result.assets].sort((a, b) => a.url.localeCompare(b.url));
-
-    //     expectAssetsToContain(sortedActual, sortedExpected);
-    //     expect(result.assets.every(a => a.content === undefined)).toBe(true); // Verify no content was embedded
-    // });
-
-
-    it('🧩 discovers assets only from initial parsed list if no nesting and embedAssets = false', async () => {
-        // Override readFile mock for this specific test to return CSS without nesting
-        mockedReadFile.mockImplementation(async (p): Promise<Buffer> => {
-             let filePath = '';
-             if (p instanceof URL) filePath = fileURLToPath(p);
-             else if (typeof p === 'string') filePath = p.startsWith('file:') ? fileURLToPath(p) : p;
-             else filePath = Buffer.isBuffer(p) ? p.toString() : String(p); // Handle Buffer/other cases simply
-
-            const normalizedPath = path.normalize(filePath);
-
-            if (normalizedPath === path.normalize(styleCssPath)) {
-                return Buffer.from('body { color: blue; } /* No nested URLs */');
-            }
-            if (normalizedPath === path.normalize(imagePath)) {
-                // This read shouldn't happen if embedAssets is false
-                console.warn("UNEXPECTED READ for imagePath in 'no nesting / embed false' test");
-                return Buffer.from('mock-png-data-image-should-not-be-read');
-            }
-             // If any other path is requested, throw ENOENT
-             const err = new Error(`ENOENT: Unexpected read in test: ${normalizedPath}`) as NodeJS.ErrnoException;
-             err.code = 'ENOENT';
-             throw err;
-        });
-
-        const parsed: ParsedHTML = { htmlContent: `<link href="style.css"><img src="image.png">`, assets: [ { type: 'css', url: 'style.css' }, { type: 'image', url: 'image.png' } ] };
-        const result = await extractAssets(parsed, false, mockBaseDir, mockLogger); // embedAssets = false
-
-        const assets: ExpectedAsset[] = [
-            { url: getResolvedFileUrl('style.css'), type: 'css', content: undefined },
-            { url: getResolvedFileUrl('image.png'), type: 'image', content: undefined }, // Initial asset, not embedded
+    it('should extract and embed assets from local HTML file', async () => {
+        // Define the initial parsed HTML structure
+        const parsed: ParsedHTML = {
+            htmlContent: '<link href="style.css"><script src="script.js">',
+            assets: [ { type: 'css', url: 'style.css' }, { type: 'js', url: 'script.js' } ] // Assets found directly in HTML
+        };
+        // Call the function under test
+        const result = await extractAssets(parsed, true, mockBaseFileUrl, mockLogger); // embedAssets = true
+        // Define the expected final assets, including nested ones
+        const expectedAssets: ExpectedAsset[] = [
+            // Top-level CSS (content should be text)
+            { type: 'css', url: resolveUrl('style.css', mockBaseFileUrl), content: expect.stringContaining('@import url("./css/deep.css");') },
+            // Top-level JS (content should be text)
+            { type: 'js', url: resolveUrl('script.js', mockBaseFileUrl), content: 'console.log("mock script");' },
+            // Nested CSS from style.css (content should be text)
+            { type: 'css', url: resolveUrl('css/deep.css', mockBaseFileUrl), content: expect.stringContaining('nested-img.png') },
+            // Image referenced in style.css (content should be data URI)
+            { type: 'image', url: resolveUrl('images/bg.png', mockBaseFileUrl), content: expect.stringMatching(/^data:image\/png;base64,/) },
+            // Font referenced in style.css (content should be data URI)
+            { type: 'font', url: resolveUrl('font/font.woff2', mockBaseFileUrl), content: expect.stringMatching(/^data:font\/woff2;base64,/) },
+            // Image referenced in deep.css (content should be data URI)
+            { type: 'image', url: resolveUrl('images/nested-img.png', mockBaseFileUrl), content: expect.stringMatching(/^data:image\/png;base64,/) }
         ];
-        const sortedExpected = [...assets].sort((a, b) => a.url.localeCompare(b.url));
-        const sortedActual = [...result.assets].sort((a, b) => a.url.localeCompare(b.url));
-
-        expectAssetsToContain(sortedActual, sortedExpected);
-        expect(mockedReadFile).toHaveBeenCalledTimes(1); // Only the CSS file should be read to check for nesting
-        expect(mockedReadFile).toHaveBeenCalledWith(expect.stringContaining(styleCssPath)); // Verify the correct file was read
-        expect(mockedStatSync).toHaveBeenCalledWith(mockBaseDir); // Base dir check
+        // Assert the final assets match the expected structure and content
+        expectAssetsToContain(result.assets, expectedAssets);
+        // Check how many times readFile was called (should be once for each unique file)
+        expect(mockReadFile).toHaveBeenCalledTimes(6); // style.css, script.js, deep.css, bg.png, font.woff2, nested-img.png
     });
 
-
-    //  it('📦 extracts nested CSS url() and @import assets recursively with embedding', async () => {
-    //     // This test is similar to the first one, just focusing on nesting.
-    //     const parsed: ParsedHTML = { htmlContent: `<link href="style.css">`, assets: [{ type: 'css', url: 'style.css' }] };
-    //     const result = await extractAssets(parsed, true, mockBaseDir, mockLogger); // embed = true
-
-    //     const assets: ExpectedAsset[] = [
-    //         { url: getResolvedFileUrl('style.css'), type: 'css', content: expect.stringContaining('@import') }, // Contains the import and url()s
-    //         { url: getResolvedFileUrl('css/deep.css'), type: 'css', content: expect.stringContaining('../images/nested-img.png') }, // Nested CSS content
-    //         { url: getResolvedFileUrl('font/relative-font.woff2'), type: 'font', content: expect.stringMatching(/^data:font\/woff2;base64,/) }, // Nested font
-    //         { url: getResolvedFileUrl('images/bg.png'), type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) }, // Nested image from style.css
-    //          { url: getResolvedFileUrl('images/nested-img.png'), type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) } // Nested image from deep.css
-    //     ];
-    //     const sortedExpected = [...assets].sort((a, b) => a.url.localeCompare(b.url));
-    //     const sortedActual = [...result.assets].sort((a, b) => a.url.localeCompare(b.url));
-
-    //     expectAssetsToContain(sortedActual, sortedExpected);
-    //     // Expect reads for: style.css, deep.css, bg.png, relative-font.woff2, nested-img.png
-    //     expect(mockedReadFile).toHaveBeenCalledTimes(5);
-    //     expect(mockedStatSync).toHaveBeenCalledWith(mockBaseDir);
-    //  });
-
-
-    //  it('📍 resolves relative URLs correctly from CSS context', async () => {
-    //      // The HTML references ./css/deep.css relative to mockBaseDir
-    //      // deep.css references ../images/nested-img.png relative to its *own* location (mockBaseDir/css/)
-    //     const parsed: ParsedHTML = { htmlContent: `<link href="./css/deep.css">`, assets: [{ type: 'css', url: './css/deep.css' }] };
-    //     const result = await extractAssets(parsed, true, mockBaseDir, mockLogger);
-
-    //     const expectedCssUrl = getResolvedFileUrl('css/deep.css');
-    //      // The nested image URL should resolve relative to mockBaseDir, becoming mockBaseDir/images/nested-img.png
-    //     const expectedImageUrl = getResolvedFileUrl('images/nested-img.png');
-
-    //     const assets: ExpectedAsset[] = [
-    //         { url: expectedCssUrl, type: 'css', content: expect.stringContaining('../images/nested-img.png') }, // Original content
-    //         { url: expectedImageUrl, type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) } // Resolved and embedded
-    //     ];
-    //     const sortedExpected = [...assets].sort((a, b) => a.url.localeCompare(b.url));
-    //     const sortedActual = [...result.assets].sort((a, b) => a.url.localeCompare(b.url));
-
-    //     expectAssetsToContain(sortedActual, sortedExpected);
-    //     // Expect reads for: deep.css, nested-img.png
-    //     expect(mockedReadFile).toHaveBeenCalledTimes(2);
-    //     // Check specific read calls
-    //     expect(mockedReadFile).toHaveBeenCalledWith(expect.stringContaining(path.normalize(deepCssPath)));
-    //      // Check that a call was made containing the nested image path fragment
-    //     expect(mockedReadFile.mock.calls.some(call => String(call[0]).includes(path.normalize('images/nested-img.png')))).toBe(true);
-    //     expect(mockedStatSync).toHaveBeenCalledWith(mockBaseDir);
-    //  });
-
-
-     it('📁 resolves local paths against basePath from HTML context', async () => {
-         // Simple case: image relative to mockBaseDir
-        const parsed: ParsedHTML = { htmlContent: `<img src="image.png">`, assets: [{ type: 'image', url: 'image.png' }] };
-        const result = await extractAssets(parsed, true, mockBaseDir, mockLogger);
-
-        const expectedImageUrl = getResolvedFileUrl('image.png');
-        const assets: ExpectedAsset[] = [
-            { url: expectedImageUrl, type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) }
+    it('should discover assets without embedding when embedAssets is false', async () => {
+        // Initial HTML with one CSS link
+        const parsed: ParsedHTML = { htmlContent: '<link href="style.css">', assets: [{ type: 'css', url: 'style.css' }] };
+        // Call with embedAssets = false
+        const result = await extractAssets(parsed, false, mockBaseFileUrl, mockLogger);
+        // Expected assets should include all discovered URLs, but content should be undefined
+        const expectedAssets: ExpectedAsset[] = [
+            { type: 'css', url: resolveUrl('style.css', mockBaseFileUrl), content: undefined },
+            { type: 'css', url: resolveUrl('css/deep.css', mockBaseFileUrl), content: undefined },
+            { type: 'image', url: resolveUrl('images/bg.png', mockBaseFileUrl), content: undefined },
+            { type: 'font', url: resolveUrl('font/font.woff2', mockBaseFileUrl), content: undefined },
+            { type: 'image', url: resolveUrl('images/nested-img.png', mockBaseFileUrl), content: undefined }
         ];
-
-        expectAssetsToContain(result.assets, assets); // No need to sort for single asset
-        expect(mockedReadFile).toHaveBeenCalledTimes(1);
-        expect(mockedReadFile).toHaveBeenCalledWith(expect.stringContaining(path.normalize(imagePath)));
-        expect(mockedStatSync).toHaveBeenCalledWith(mockBaseDir);
-     });
-
-
-     it('🌍 resolves remote assets using base URL from HTML context', async () => {
-          // HTML is at https://example.com/pages/about.html
-          // CSS link is ../styles/style.css -> resolves to https://example.com/styles/style.css
-          // Img link is /images/logo.png -> resolves to https://example.com/images/logo.png
-          // style.css contains url("/img/remote-bg.jpg?v=1") -> resolves relative to CSS: https://example.com/img/remote-bg.jpg?v=1
-         const remoteHtmlUrl = 'https://example.com/pages/about.html';
-         const parsed: ParsedHTML = {
-             htmlContent: `<html><head><link rel="stylesheet" href="../styles/style.css"></head><body><img src="/images/logo.png"></body></html>`,
-             assets: [
-                 { type: 'css', url: '../styles/style.css' }, // Relative URL
-                 { type: 'image', url: '/images/logo.png' }   // Absolute path URL
-             ]
-         };
-
-         const expectedCssUrl = 'https://example.com/styles/style.css';
-         const expectedLogoUrl = 'https://example.com/images/logo.png';
-          // This URL is found *inside* the mocked style.css content
-         const expectedNestedImageUrl = 'https://example.com/img/remote-bg.jpg?v=1';
-
-         const result = await extractAssets(parsed, true, remoteHtmlUrl, mockLogger); // Use remote URL as base
-
-         const assets: ExpectedAsset[] = [
-             { url: expectedCssUrl, type: 'css', content: expect.stringContaining('remote-bg.jpg') }, // Fetched CSS content
-             { url: expectedLogoUrl, type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) }, // Embedded logo
-             { url: expectedNestedImageUrl, type: 'image', content: expect.stringMatching(/^data:image\/jpeg;base64,/) } // Embedded nested image from CSS
-         ];
-         const sortedExpected = [...assets].sort((a,b)=>a.url.localeCompare(b.url));
-         const sortedActual = [...result.assets].sort((a,b)=>a.url.localeCompare(b.url));
-
-         expectAssetsToContain(sortedActual, sortedExpected);
-         // Expect 3 axios calls: style.css, logo.png, remote-bg.jpg
-         expect(mockedAxiosGet).toHaveBeenCalledTimes(3);
-         expect(mockedAxiosGet).toHaveBeenCalledWith(expectedCssUrl, expect.any(Object)); // Axios called with resolved URL
-         expect(mockedAxiosGet).toHaveBeenCalledWith(expectedLogoUrl, expect.any(Object)); // Axios called with resolved URL
-         expect(mockedAxiosGet).toHaveBeenCalledWith(expectedNestedImageUrl, expect.any(Object)); // Axios called with resolved nested URL
-         expect(mockedReadFile).not.toHaveBeenCalled(); // No local file reads
-         expect(mockedStatSync).not.toHaveBeenCalled(); // No local stat calls
-      });
-
-
-    //  it('🧠 handles deep nested relative local paths from HTML context', async () => {
-    //      // HTML is notionally in mockBaseDir/pages/about/index.html (using deepHtmlDirPath as base)
-    //      // Link is ../../css/deep.css -> resolves to mockBaseDir/css/deep.css
-    //      // deep.css contains ../images/nested-img.png -> resolves to mockBaseDir/images/nested-img.png
-    //      const parsed: ParsedHTML = { htmlContent: `<link href="../../css/deep.css">`, assets: [{ type: 'css', url: '../../css/deep.css' }] };
-    //      const result = await extractAssets(parsed, true, deepHtmlDirPath, mockLogger); // Use deep path as base
-
-    //      const expectedCssUrl = getResolvedFileUrl('css/deep.css'); // Resolves correctly relative to mockBaseDir
-    //      const expectedNestedImageUrl = getResolvedFileUrl('images/nested-img.png'); // Resolves correctly relative to mockBaseDir
-
-    //      const assets: ExpectedAsset[] = [
-    //          { url: expectedCssUrl, type: 'css', content: expect.stringContaining('../images/nested-img.png') },
-    //          { url: expectedNestedImageUrl, type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) }
-    //      ];
-    //      const sortedExpected = [...assets].sort((a, b) => a.url.localeCompare(b.url));
-    //      const sortedActual = [...result.assets].sort((a, b) => a.url.localeCompare(b.url));
-
-    //      expectAssetsToContain(sortedActual, sortedExpected);
-    //      // Expect reads for: deep.css, nested-img.png
-    //      expect(mockedReadFile).toHaveBeenCalledTimes(2);
-    //      // Check that the correct resolved paths were read
-    //      expect(mockedReadFile).toHaveBeenCalledWith(expect.stringContaining(path.normalize(deepCssPath)));
-    //      expect(mockedReadFile.mock.calls.some(call => String(call[0]).includes(path.normalize('images/nested-img.png')))).toBe(true);
-    //      expect(mockedStatSync).toHaveBeenCalledWith(deepHtmlDirPath); // Initial base check
-    //  });
-
-
-    //  it('🧼 skips base64 data URIs but processes other assets normally', async () => {
-    //      // HTML has a link to datauri.css and an embedded data URI image
-    //      // datauri.css links to image.png
-    //      const parsed: ParsedHTML = {
-    //          htmlContent: `<link href="datauri.css"><img src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==">`,
-    //          assets: [
-    //              { type: 'css', url: 'datauri.css' },
-    //              // Note: The parser *should not* produce an asset for the data URI img src
-    //          ]
-    //      };
-    //      const result = await extractAssets(parsed, true, mockBaseDir, mockLogger);
-
-    //      // Expected assets: datauri.css and the image.png it links to
-    //      const assets: ExpectedAsset[] = [
-    //          { url: getResolvedFileUrl('datauri.css'), type: 'css', content: expect.stringContaining('url("image.png")') },
-    //          { url: getResolvedFileUrl('image.png'), type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) }
-    //      ];
-    //      const sortedExpected = [...assets].sort((a, b) => a.url.localeCompare(b.url));
-    //      const sortedActual = [...result.assets].sort((a, b) => a.url.localeCompare(b.url));
-
-    //      expectAssetsToContain(sortedActual, sortedExpected);
-    //      // Check that no asset with a 'data:' URL was included in the final list
-    //      expect(result.assets.some(a => a.url.startsWith('data:'))).toBe(false);
-    //      // Expect reads for: datauri.css, image.png
-    //      expect(mockedReadFile).toHaveBeenCalledTimes(2);
-    //      expect(mockedStatSync).toHaveBeenCalledWith(mockBaseDir);
-    //  });
-
-
-     it('⚠️ handles remote asset fetch errors gracefully (network)', async () => {
-         const errorUrl = 'https://fail.net/style.css'; // Mocked to return 500
-         const successUrl = 'https://okay.net/script.js'; // Mocked to return 200
-         const parsed: ParsedHTML = {
-             htmlContent: `<link href="<span class="math-inline">\{errorUrl\}"\><script src\="</span>{successUrl}"></script>`,
-             assets: [{ type: 'css', url: errorUrl }, { type: 'js', url: successUrl }]
-         };
-         const result = await extractAssets(parsed, true, 'https://base.com/', mockLogger); // Base URL for context
-
-         // Expect the failed asset with undefined content, and the successful one embedded
-         const assets: ExpectedAsset[] = [
-             { url: errorUrl, type: 'css', content: undefined }, // Failed fetch
-             { url: successUrl, type: 'js', content: expect.stringContaining('remote script') } // Successful fetch
-         ];
-         const sortedExpected = [...assets].sort((a,b)=>a.url.localeCompare(b.url));
-         const sortedActual = [...result.assets].sort((a,b)=>a.url.localeCompare(b.url));
-
-         expectAssetsToContain(sortedActual, sortedExpected);
-         // Both URLs should have been attempted
-         expect(mockedAxiosGet).toHaveBeenCalledTimes(2);
-         expect(mockedAxiosGet).toHaveBeenCalledWith(errorUrl, expect.any(Object));
-         expect(mockedAxiosGet).toHaveBeenCalledWith(successUrl, expect.any(Object));
-         // Expect a warning log for the failed asset
-         expect(mockLoggerWarnSpy).toHaveBeenCalledTimes(1);
-         expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(`Failed to fetch remote asset ${errorUrl}: Status 500`));
-         expect(mockLoggerErrorSpy).not.toHaveBeenCalled(); // Should be a warning, not an error
-     });
-
-
-     /* it('⚠️ handles local asset fetch errors gracefully (file not found)', async () => {
-         const errorPath = 'nonexistent.css'; // Mocked to throw ENOENT on read
-         const successPath = 'style.css';    // Mocked to read successfully (and contains nested assets)
-         const parsed: ParsedHTML = {
-             htmlContent: `<link href="<span class="math-inline">\{errorPath\}"\><link href\="</span>{successPath}">`,
-             assets: [{ type: 'css', url: errorPath }, { type: 'css', url: successPath }]
-         };
-         const result = await extractAssets(parsed, true, mockBaseDir, mockLogger);
-
-         const resolvedErrorUrl = getResolvedFileUrl(errorPath);
-         const resolvedSuccessUrl = getResolvedFileUrl(successPath);
-         // Nested assets from the *successful* style.css read
-         const resolvedNestedCssUrl = getResolvedFileUrl('css/deep.css');
-         const resolvedNestedFontUrl = getResolvedFileUrl('font/relative-font.woff2');
-         const resolvedNestedImageUrl = getResolvedFileUrl('images/bg.png');
-         const resolvedDeepNestedImageUrl = getResolvedFileUrl('images/nested-img.png'); // From deep.css
-
-         const assets: ExpectedAsset[] = [
-             { url: resolvedErrorUrl, type: 'css', content: undefined }, // Failed read
-             { url: resolvedSuccessUrl, type: 'css', content: expect.stringContaining('@import') }, // Successful read
-             // Nested assets from style.css and deep.css
-             { url: resolvedNestedCssUrl, type: 'css', content: expect.stringContaining('../images/nested-img.png') },
-             { url: resolvedNestedFontUrl, type: 'font', content: expect.stringMatching(/^data:font\/woff2;base64,/) },
-             { url: resolvedNestedImageUrl, type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) },
-             { url: resolvedDeepNestedImageUrl, type: 'image', content: expect.stringMatching(/^data:image\/png;base64,/) },
-         ];
-         const sortedExpected = [...assets].sort((a, b) => a.url.localeCompare(b.url));
-         const sortedActual = [...result.assets].sort((a, b) => a.url.localeCompare(b.url));
-
-         expectAssetsToContain(sortedActual, sortedExpected);
-         // Expect reads attempted for: nonexistent.css, style.css, deep.css, bg.png, relative-font.woff2, nested-img.png
-         expect(mockedReadFile).toHaveBeenCalledTimes(6);
-         // Verify the failed path was attempted
-         expect(mockedReadFile).toHaveBeenCalledWith(expect.stringContaining(path.normalize(nonexistentPath)));
-         // Expect a warning log for the ENOENT error
-         expect(mockLoggerWarnSpy).toHaveBeenCalledTimes(1);
-         // Use the normalized path in the log message check for consistency
-         expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(`File not found (ENOENT) for asset: ${path.normalize(nonexistentPath)}`));
-          expect(result.assets.filter(a => a.content !== undefined).length).toBe(5); // 5 assets should have content
-         expect(mockedStatSync).toHaveBeenCalledWith(mockBaseDir); // Base dir check
-     }); */
-
-
-    //   it('🔄 handles asset cycles gracefully (visitedUrls set)', async () => {
-    //      // cycle1.css imports cycle2.css, cycle2.css imports cycle1.css
-    //     const parsed: ParsedHTML = { htmlContent: `<link href="cycle1.css">`, assets: [{ type: 'css', url: 'cycle1.css' }] };
-    //     const result = await extractAssets(parsed, true, mockBaseDir, mockLogger);
-
-    //     const resolvedCss1Url = getResolvedFileUrl('cycle1.css');
-    //     const resolvedCss2Url = getResolvedFileUrl('cycle2.css');
-
-    //     // Both CSS files should be present with their original content
-    //     const assets: ExpectedAsset[] = [
-    //         { url: resolvedCss1Url, type: 'css', content: expect.stringContaining('@import url("cycle2.css")') },
-    //         { url: resolvedCss2Url, type: 'css', content: expect.stringContaining('@import url("cycle1.css")') }
-    //     ];
-    //     const sortedExpected = [...assets].sort((a, b) => a.url.localeCompare(b.url));
-    //     const sortedActual = [...result.assets].sort((a, b) => a.url.localeCompare(b.url));
-
-    //     expectAssetsToContain(sortedActual, sortedExpected);
-    //     // Each file should be read exactly once due to the visitedUrls mechanism
-    //     expect(mockedReadFile).toHaveBeenCalledTimes(2);
-    //     expect(mockedReadFile).toHaveBeenCalledWith(expect.stringContaining(path.normalize(cycle1CssPath)));
-    //     expect(mockedReadFile).toHaveBeenCalledWith(expect.stringContaining(path.normalize(cycle2CssPath)));
-    //     // No warnings or errors about cycles or limits should be logged
-    //     expect(mockLoggerWarnSpy).not.toHaveBeenCalledWith(expect.stringContaining('cycle'));
-    //     expect(mockLoggerErrorSpy).not.toHaveBeenCalledWith(expect.stringContaining('infinite loop'));
-    //     expect(mockLoggerErrorSpy).not.toHaveBeenCalledWith(expect.stringContaining('limit hit'));
-    //     expect(mockedStatSync).toHaveBeenCalledWith(mockBaseDir);
-    //   });
-
-
-    // =================== EDGE CASE / COVERAGE TESTS ===================
-
-    it('⚠️ handles non-ENOENT local file read errors (EACCES)', async () => {
-        const parsed: ParsedHTML = { htmlContent: `<link href="unreadable.css">`, assets: [{ type: 'css', url: 'unreadable.css' }] };
-        const result = await extractAssets(parsed, true, mockBaseDir, mockLogger); // embed=true
-
-        expect(result.assets).toHaveLength(1); // Asset should still be listed
-        const asset = result.assets[0];
-        expect(asset.url).toBe(getResolvedFileUrl('unreadable.css'));
-        expect(asset.content).toBeUndefined(); // Content fetching failed
-        expect(asset.type).toBe('css');
-
-        // Expect a warning about the EACCES error
-        expect(mockLoggerWarnSpy).toHaveBeenCalledTimes(1);
-        // Use normalized path in expectation
-        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(`Permission denied (EACCES) reading asset: ${path.normalize(unreadablePath)}`));
-        expect(mockLoggerErrorSpy).not.toHaveBeenCalled(); // Should not be a fatal error
+        // Assert the structure matches
+        expectAssetsToContain(result.assets, expectedAssets);
+        // readFile should only be called for CSS files (to parse them), not for images/fonts when not embedding
+        expect(mockReadFile).toHaveBeenCalledTimes(2); // Only style.css, deep.css
     });
 
+    it('should handle remote assets and their nested dependencies', async () => {
+        // Define a remote base URL
+        const remoteUrl = 'https://example.com/page.html';
+        // Initial HTML structure with remote assets
+        const parsed: ParsedHTML = {
+            htmlContent: '<link href="styles/main.css"><script src="/js/script.js">', // Relative and absolute paths
+            assets: [ { type: 'css', url: 'styles/main.css' }, { type: 'js', url: '/js/script.js' } ]
+        };
+        // Call with embedAssets = true
+        const result = await extractAssets(parsed, true, remoteUrl, mockLogger);
+        // Expected assets, including nested remote image from the mocked CSS content
+        const expectedAssets: ExpectedAsset[] = [
+            { type: 'css', url: resolveUrl('styles/main.css', remoteUrl), content: expect.stringContaining('background') }, // Text content
+            { type: 'js', url: resolveUrl('/js/script.js', remoteUrl), content: 'console.log("remote script");' }, // Text content
+            { type: 'image', url: resolveUrl('/images/remote-bg.jpg', remoteUrl), content: expect.stringMatching(/^data:image\/jpeg;base64,/) } // Data URI
+        ];
+        // Assert the results
+        expectAssetsToContain(result.assets, expectedAssets);
+        // Check that axios.get was called for each remote asset
+        expect(mockAxiosGet).toHaveBeenCalledTimes(3); // main.css, script.js, remote-bg.jpg
+        // Ensure local file reading was not attempted
+        expect(mockReadFile).not.toHaveBeenCalled();
+    });
 
-    it('⚠️ handles non-Axios remote fetch errors (e.g., invalid URL object passed to fetch)', async () => {
-        const invalidUrlString = 'invalid-protocol://weird'; // Not http/https
-        const parsed: ParsedHTML = { htmlContent: ``, assets: [{ type: 'js', url: invalidUrlString }] };
-
-        // This test relies on the internal URL parsing/validation within fetchAsset/resolveAssetUrl
-        const result = await extractAssets(parsed, true, 'https://base.com/', mockLogger);
-
-        // --- Assert Results & Logging ---
-        // The primary check is the warning log from fetchAsset (or resolveAssetUrl if it catches it earlier)
-         // Expect a warning because the protocol is unsupported for fetching.
-        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(
-            `Unsupported protocol "invalid-protocol:" in URL: ${invalidUrlString}` // Message from fetchAsset
-        ));
-         expect(mockLoggerErrorSpy).not.toHaveBeenCalled(); // Should not be a fatal error
-
-
-        // The asset might be included in the list but without content, or excluded entirely
-        // depending on where the error occurs (resolution vs. fetching).
-        // Let's check if it's present but without content.
-        const foundAsset = result.assets.find(a => a.url === invalidUrlString);
-        expect(foundAsset).toBeDefined(); // It should likely still be in the list from the initial parse
-        if (foundAsset) {
-            expect(foundAsset.content).toBeUndefined(); // Content fetching would fail
-            expect(foundAsset.type).toBe('js');
-             expect(result.assets).toHaveLength(1); // Only this asset was processed
-        } else {
-            // If resolveAssetUrl failed very early, the list might be empty
-             expect(result.assets).toHaveLength(0);
-        }
-
-
-        // Fetching (Axios or fs) should not have been attempted
-        expect(mockedAxiosGet).not.toHaveBeenCalled();
-        expect(mockedReadFile).not.toHaveBeenCalled();
+    it('should handle ENOENT errors when reading local files', async () => {
+        // HTML references a file that doesn't exist in the mock setup
+        const parsed: ParsedHTML = { htmlContent: '<link href="nonexistent.file">', assets: [{ type: 'css', url: 'nonexistent.file' }] };
+        // Call extractor
+        const result = await extractAssets(parsed, true, mockBaseFileUrl, mockLogger);
+        // Expect the asset list to contain the entry, but with undefined content
+        expect(result.assets).toHaveLength(1);
+        expect(result.assets[0].content).toBeUndefined();
+        // Expect a warning log indicating the file was not found
+        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(`File not found (ENOENT) for asset: ${normalizePath(filePaths.nonexistent)}`));
     });
 
+    it('should handle permission denied errors when reading local files', async () => {
+        // HTML references a file set up to trigger EACCES in the mock readFile
+        const parsed: ParsedHTML = { htmlContent: '<link href="unreadable.file">', assets: [{ type: 'css', url: 'unreadable.file' }] };
+        // Call extractor
+        const result = await extractAssets(parsed, true, mockBaseFileUrl, mockLogger);
+        // Expect the asset with undefined content
+        expect(result.assets).toHaveLength(1);
+        expect(result.assets[0].content).toBeUndefined();
+        // *** CORRECTED EXPECTATION ***: Check for the specific EACCES warning message logged by the updated extractor.ts
+        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(
+            expect.stringContaining(`Permission denied (EACCES) reading asset: ${normalizePath(filePaths.unreadable)}`)
+        );
+        // *** CORRECTED EXPECTATION ***: Verify readFile was called with ONLY the path argument
+        expect(mockReadFile).toHaveBeenCalledWith(normalizePath(filePaths.unreadable));
+    });
 
-    it('⚠️ handles network timeout errors specifically', async () => {
-        const timeoutUrl = 'https://timeout.net/resource.png'; // Mocked to throw timeout AxiosError
-        const parsed: ParsedHTML = { htmlContent: `<img src="${timeoutUrl}">`, assets: [{ type: 'image', url: timeoutUrl }] };
-        const result = await extractAssets(parsed, true, 'https://timeout.net/', mockLogger); // Base URL context
+    it('should handle HTTP errors when fetching remote assets', async () => {
+        const remoteUrl = 'https://example.com/page.html';
+        // Resolve the URL that will trigger a 404 in the axios mock
+        const errorCssUrl = resolveUrl('styles/error.css', remoteUrl);
+        // HTML referencing the error URL
+        const parsed: ParsedHTML = { htmlContent: `<link href="${errorCssUrl}">`, assets: [{ type: 'css', url: errorCssUrl }] };
+        // Call extractor
+        const result = await extractAssets(parsed, true, remoteUrl, mockLogger);
+        // Expect the asset with undefined content
+        expect(result.assets).toHaveLength(1);
+        expect(result.assets[0].content).toBeUndefined();
+        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(
+            expect.stringContaining(`Failed to fetch remote asset ${errorCssUrl}: Request failed with status code 404 (Code: N/A)`) // Changed undefined to N/A
+        );
+    });
 
-        expect(result.assets).toHaveLength(1); // Asset is listed
-        const asset = result.assets[0];
-        expect(asset.url).toBe(timeoutUrl);
-        expect(asset.content).toBeUndefined(); // Fetch failed due to timeout
-        expect(asset.type).toBe('image');
+    it('should handle timeout errors when fetching remote assets', async () => {
+        const remoteUrl = 'https://example.com/page.html';
+        // Resolve the URL that triggers a timeout (ECONNABORTED) in the axios mock
+        const timeoutCssUrl = resolveUrl('styles/timeout.css', remoteUrl);
+        // HTML referencing the timeout URL
+        const parsed: ParsedHTML = { htmlContent: `<link href="${timeoutCssUrl}">`, assets: [{ type: 'css', url: timeoutCssUrl }] };
+        // Call extractor
+        const result = await extractAssets(parsed, true, remoteUrl, mockLogger);
+        // Expect the asset with undefined content
+        expect(result.assets).toHaveLength(1);
+        expect(result.assets[0].content).toBeUndefined();
+        // *** CORRECTED EXPECTATION ***: Check for the specific warning logged by the updated fetchAsset, including the code
+        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(
+            // Match the simplified log format exactly
+            expect.stringContaining(`Failed to fetch remote asset ${timeoutCssUrl}: Timeout of 10000ms exceeded (Code: ECONNABORTED)`)
+        );
+    });
 
-        // Expect a specific warning log for the timeout
+    it('should handle invalid UTF-8 in CSS files by falling back to base64', async () => {
+         // HTML referencing the CSS file with invalid UTF-8 content
+        const parsed: ParsedHTML = { htmlContent: '<link href="invalid-utf8.css">', assets: [{ type: 'css', url: 'invalid-utf8.css' }] };
+         // Call extractor
+        const result = await extractAssets(parsed, true, mockBaseFileUrl, mockLogger);
+         // Resolve the expected URL
+        const expectedUrl = resolveUrl('invalid-utf8.css', mockBaseFileUrl);
+         // Expect one asset in the result
+        expect(result.assets).toHaveLength(1);
+         // Expect the content to be a data URI containing the base64 representation of the original buffer
+        expect(result.assets[0].content).toEqual(`data:text/css;base64,${invalidUtf8Buffer.toString('base64')}`);
+         // *** CORRECTED EXPECTATION (from previous step) ***: Expect the single, combined warning message
+        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(
+            expect.stringContaining(`Could not decode css asset ${expectedUrl} as valid UTF-8 text. Falling back to base64 data URI.`)
+        );
+        // Ensure only one warning related to this was logged
         expect(mockLoggerWarnSpy).toHaveBeenCalledTimes(1);
-         // Check the log message includes the status, code, and timeout duration from the mock error
-        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(
-            `Failed to fetch remote asset ${timeoutUrl}: Status 408 - Request Timeout. Code: ECONNABORTED, Message: timeout of 10000ms exceeded`
-        ));
-        expect(mockLoggerErrorSpy).not.toHaveBeenCalled();
-    });
-    
-    it('❓ handles unsupported URL protocols (e.g., ftp)', async () => {
-        const ftpUrl = 'ftp://example.com/image.jpg'; const parsed: ParsedHTML = { htmlContent: `<img src="${ftpUrl}">`, assets: [{ type: 'image', url: ftpUrl }] };
-        const result = await extractAssets(parsed, true, mockBaseDir, mockLogger);
-        expect(result.assets).toHaveLength(1); expect(result.assets[0].url).toBe(ftpUrl); expect(result.assets[0].content).toBeUndefined(); expect(mockLoggerWarnSpy).toHaveBeenCalledTimes(1);
-        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(`Unsupported protocol "ftp:" in URL: ${ftpUrl}`));
-        expect(mockedAxiosGet).not.toHaveBeenCalled(); expect(mockedReadFile).not.toHaveBeenCalled();
     });
-    it('🤔 handles assets with "other" types (attempts text, falls back to base64 if invalid UTF-8)', async () => {
-        const otherFileUrl = getResolvedFileUrl('file.other');
-        
-        // Clear mocks for this specific test
-        mockReadFileFn.mockReset();
-        mockLoggerWarnSpy.mockClear();
-        mockLoggerDebugSpy.mockClear();
-        
-        // Clear any previous mocks if needed (though beforeEach should handle it)
-        mockedReadFile.mockClear();
-
-        mockedReadFile.mockImplementation(async (fileUrlOrPath): Promise<Buffer> => {
-            let filePath: string = '';
 
-            // --- Determine the actual file path string ---
-            // (This logic should handle various ways fs.readFile might be called)
-            if (typeof fileUrlOrPath === 'string') {
-                // Handle both file URLs and regular paths passed as strings
-                try {
-                filePath = fileUrlOrPath.startsWith('file:') ? fileURLToPath(fileUrlOrPath) : fileUrlOrPath;
-                } catch (e) {
-                console.error(`[DEBUG MOCK readFile - other type test] Error converting string path/URL: ${fileUrlOrPath}`, e);
-                throw new Error(`Could not derive path from string: ${fileUrlOrPath}`);
-                }
-            } else if (fileUrlOrPath instanceof URL && fileUrlOrPath.protocol === 'file:') {
-                // Handle URL objects
-                try {
-                filePath = fileURLToPath(fileUrlOrPath);
-                } catch (e) {
-                    console.error(`[DEBUG MOCK readFile - other type test] Error converting URL object: ${fileUrlOrPath.href}`, e);
-                    throw new Error(`Could not derive path from URL object: ${fileUrlOrPath.href}`);
-                }
-            } else if (typeof (fileUrlOrPath as any)?.path === 'string') { // Basic check for FileHandle-like object
-                filePath = (fileUrlOrPath as any).path;
-            } else {
-                // Log or throw for unexpected input types
-                const inputDesc = typeof fileUrlOrPath === 'object' ? JSON.stringify(fileUrlOrPath) : String(fileUrlOrPath);
-                console.error(`[DEBUG MOCK readFile - other type test] Unexpected input type: ${typeof fileUrlOrPath}, value: ${inputDesc}`);
-                throw new Error(`Unexpected input type to readFile mock: ${typeof fileUrlOrPath}`);
-            }
-
-            // Normalize for consistent comparison
-            const normalizedPath = path.normalize(filePath);
-            const normalizedUnknownFilePath = path.normalize(unknownFilePath); // Normalize the target path too
-
-            // Log what's being requested (optional, but helpful)
-            // Remember: console is mocked, might need DEBUG=true env var to see this
-            console.log(`[DEBUG MOCK readFile - other type test] Requested normalized path: ${normalizedPath}`);
-            console.log(`[DEBUG MOCK readFile - other type test] Comparing against: ${normalizedUnknownFilePath}`);
+    it('should avoid circular references in CSS imports', async () => {
+        // HTML referencing the start of a CSS import cycle
+        const parsed: ParsedHTML = { htmlContent: '<link href="cycle1.css">', assets: [{ type: 'css', url: 'cycle1.css' }] };
+        // Call extractor
+        const result = await extractAssets(parsed, true, mockBaseFileUrl, mockLogger);
+        // Expected assets: both cycle1.css and cycle2.css should be found, but the loop should terminate
+        const expectedAssets: ExpectedAsset[] = [
+            { type: 'css', url: resolveUrl('cycle1.css', mockBaseFileUrl), content: expect.stringContaining('@import url("cycle2.css");') },
+            { type: 'css', url: resolveUrl('cycle2.css', mockBaseFileUrl), content: expect.stringContaining('@import url("cycle1.css");') } // Should find cycle2
+        ];
+        // Assert the expected assets were found
+        expectAssetsToContain(result.assets, expectedAssets);
+        // Ensure no loop limit error was logged
+        expect(mockLoggerErrorSpy).not.toHaveBeenCalled(); // Check error spy specifically
+        // *** CORRECTED EXPECTATION ***: Verify both CSS files were read (with only one argument)
+        expect(mockReadFile).toHaveBeenCalledWith(normalizePath(filePaths.cycle1Css));
+        expect(mockReadFile).toHaveBeenCalledWith(normalizePath(filePaths.cycle2Css));
+    });
 
-            // --- Specific Check for this Test ---
-            // Compare normalized requested path with the normalized path of 'file.other'
-            if (normalizedPath === normalizedUnknownFilePath) {
-                console.log(`[DEBUG MOCK readFile - other type test] MATCH! Returning invalidUtf8Buffer for ${normalizedPath}`);
-                // Make sure 'invalidUtf8Buffer' is accessible here (defined outside/above)
-                return invalidUtf8Buffer;
+    it('should enforce maximum iteration limit to prevent infinite loops', async () => {
+        // *** CORRECTED MOCK IMPLEMENTATION ***: Mock readFile to generate new CSS files endlessly
+        const iterationTestReadFileMock = async (filePathArg: PathLike | FileHandle): Promise<Buffer | string> => {
+            let normalizedPath: string = '';
+            try {
+                if (filePathArg instanceof URL) { normalizedPath = path.normalize(fileURLToPath(filePathArg)); }
+                else if (typeof filePathArg === 'string') { normalizedPath = path.normalize(filePathArg.startsWith('file:') ? fileURLToPath(filePathArg) : filePathArg); }
+                else { throw new Error('Unsupported readFile input type in iteration mock'); }
+            } catch(e) { console.error("Error normalizing path in iteration mock:", filePathArg, e); throw e; }
+            const filename = path.basename(normalizedPath);
+            const match = filename.match(/gen_(\d+)\.css$/);
+            const isStart = filename === 'start.css';
+            if (match || isStart) {
+                const currentNum = match ? parseInt(match[1], 10) : 0;
+                const nextNum = currentNum + 1;
+                const nextFileName = `gen_${nextNum}.css`;
+                return Buffer.from(`@import url("${nextFileName}");`);
             }
-
-            // Fallback for any other unexpected file reads *within this specific test*
-            // This helps catch if the test is trying to read other files unexpectedly
-            console.warn(`[DEBUG MOCK readFile - other type test] Unexpected path requested: ${normalizedPath}. Returning default.`);
-            // You could throw an error here instead if NO other file should be read
-            // throw new Error(`Unexpected file read requested in 'other type' test: ${normalizedPath}`);
-            return Buffer.from(`/* Default content for unexpected path in 'other type' test: ${normalizedPath} */`);
-        });
-                
-        // Run the test
-        const parsed: ParsedHTML = { 
-            htmlContent: `<a href="file.other">Link</a>`, 
-            assets: [{ type: 'other' as Asset['type'], url: 'file.other' }] 
+            const error: NodeJSErrnoException = new Error(`ENOENT (Mock Iteration): Unexpected path ${normalizedPath}`); error.code = 'ENOENT'; throw error;
         };
-        
-        const resultInvalid = await extractAssets(parsed, true, mockBaseDir, mockLogger);
-        
-        // Debug logging
-        console.log('Actual asset content:', resultInvalid.assets[0].content);
-        console.log('Expected base64:', `data:application/octet-stream;base64,${invalidUtf8Buffer.toString('base64')}`);
-        
-        // Assertions
-        expect(resultInvalid.assets).toHaveLength(1);
-        expect(resultInvalid.assets[0].url).toBe(otherFileUrl);
-        expect(resultInvalid.assets[0].type).toBe('other');
-        expect(resultInvalid.assets[0].content).toBe(`data:application/octet-stream;base64,${invalidUtf8Buffer.toString('base64')}`);
+        mockReadFile.mockImplementation(iterationTestReadFileMock as any);
+
+        const parsed: ParsedHTML = { htmlContent: '<link href="start.css">', assets: [{ type: 'css', url: 'start.css' }] };
+        const result = await extractAssets(parsed, true, mockBaseFileUrl, mockLogger);
+
+        expect(result.assets.length).toBeGreaterThan(0);
+        // *** CORRECTED EXPECTATION ***: Check that the ERROR logger was called exactly TWICE
+        expect(mockLoggerErrorSpy).toHaveBeenCalledTimes(2);
+        // *** CORRECTED EXPECTATION ***: Check that the FIRST error message contains the loop limit text
+        expect(mockLoggerErrorSpy).toHaveBeenNthCalledWith(1, expect.stringContaining('Asset extraction loop limit hit'));
+        // *** CORRECTED EXPECTATION ***: Check the SECOND error message contains the remaining queue text
+        expect(mockLoggerErrorSpy).toHaveBeenNthCalledWith(2, expect.stringContaining('Remaining queue sample'));
     });
 
-    // Skipping this test as the spy capture seems unreliable in this env/setup
-    it.skip('⚠️ warns if base URL cannot be determined for relative paths from HTML', async () => {
-        const invalidInput = 'invalid-protocol://test'; const parsed: ParsedHTML = { htmlContent: `<img src="relative/image.png">`, assets: [{ type: 'image', url: 'relative/image.png' }] };
-        await extractAssets(parsed, true, invalidInput, mockLogger);
-        expect(mockLoggerErrorSpy).toHaveBeenCalledTimes(1); // Expect ERROR log from determineBaseUrl catch
-        expect(mockLoggerErrorSpy).toHaveBeenCalledWith(expect.stringContaining(`💀 Failed to determine base URL for "${invalidInput}"`));
-        expect(mockLoggerWarnSpy).toHaveBeenCalledTimes(1); // Expect WARNING log from resolveAssetUrl
-        expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(`Cannot resolve relative URL "relative/image.png" - Base context URL was not provided or determined.`));
+    it('should handle data URIs in CSS without trying to fetch them', async () => {
+        // HTML referencing CSS that contains a data URI
+        const parsed: ParsedHTML = { htmlContent: '<link href="data-uri.css">', assets: [{ type: 'css', url: 'data-uri.css' }] };
+        // Call extractor
+        const result = await extractAssets(parsed, true, mockBaseFileUrl, mockLogger);
+        // Expect only the CSS file itself to be in the final assets
+        expect(result.assets).toHaveLength(1);
+        expect(result.assets[0].url).toEqual(resolveUrl('data-uri.css', mockBaseFileUrl));
+        // *** CORRECTED EXPECTATION ***: Verify the CSS file was read (with only one argument)
+        expect(mockReadFile).toHaveBeenCalledWith(normalizePath(filePaths.dataUriCss));
+        // Crucially, verify that no HTTP request was made (axios mock shouldn't be called)
+        expect(mockAxiosGet).not.toHaveBeenCalled();
     });
 
-    // it('⚠️ handles failure to determine CSS base URL gracefully', async () => {
-    //     const invalidCssFileUrl = 'file:///__INVALID_PATH_CHARACTERS__?query#hash'; mockedReadFile.mockImplementation(async (p) => Buffer.from('body { color: red; }'));
-    //     const parsed: ParsedHTML = { htmlContent: `<link href="${invalidCssFileUrl}">`, assets: [{ type: 'css', url: invalidCssFileUrl }] };
-    //     await extractAssets(parsed, true, mockBaseDir, mockLogger);
-    //     expect(mockLoggerErrorSpy).toHaveBeenCalledTimes(1); // Expect ERROR log from fetchAsset
-    //     expect(mockLoggerErrorSpy).toHaveBeenCalledWith(expect.stringContaining(`Could not convert file URL to path: ${invalidCssFileUrl}. Error:`));
-    //     expect(mockLoggerWarnSpy).not.toHaveBeenCalledWith(expect.stringContaining(`Could not determine base URL context for CSS file`)); // Should not log this warning
-    // });
-
-    // it('⚠️ handles failure to decode CSS content for parsing (logs warning, embeds base64)', async () => {
-    //     const invalidCssUrl = getResolvedFileUrl('invalid-utf8.css');
-    //     const parsed: ParsedHTML = { htmlContent: `<link href="invalid-utf8.css">`, assets: [{ type: 'css', url: 'invalid-utf8.css' }] };
-    //     const result = await extractAssets(parsed, true, mockBaseDir, mockLogger);
-    //     // --- Verify Logging ---
-    //     // **CORRECTED EXPECTATION ORDER:**
-    //     // 1. Expect the warning about failed decoding *for parsing* (logged first)
-    //     expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(
-    //         `Failed to decode CSS content for parsing ${invalidCssUrl} due to invalid UTF-8 sequences.` // <-- Corrected Expectation
-    //     ));
-    //     // 2. Also expect the warning about falling back to base64 for the *embedding* part (logged later)
-    //      expect(mockLoggerWarnSpy).toHaveBeenCalledWith(expect.stringContaining(
-    //          `Could not represent css ${invalidCssUrl} as valid UTF-8 text, falling back to base64 data URI.`
-    //      ));
-    //     // 3. Expect exactly these two warnings
-    //     expect(mockLoggerWarnSpy).toHaveBeenCalledTimes(2);
-    //     // --- Verify Asset ---
-    //     expect(result.assets).toHaveLength(1); expect(result.assets[0].url).toBe(invalidCssUrl); expect(result.assets[0].content).toBe(`data:text/css;base64,${invalidUtf8Buffer.toString('base64')}`);
-    // });
+    it('should handle CSS URLs with query parameters and fragments correctly', async () => {
+        // HTML referencing CSS which contains a URL with query/fragment
+        const parsed: ParsedHTML = { htmlContent: '<link href="complex-url.css">', assets: [{ type: 'css', url: 'complex-url.css' }] };
+        // Call extractor
+        const result = await extractAssets(parsed, true, mockBaseFileUrl, mockLogger);
+        // Define the expected resolved URLs
+        const expectedCssUrl = resolveUrl('complex-url.css', mockBaseFileUrl);
+        // The URL for the nested asset keeps the query/fragment
+        const expectedBgUrlWithQuery = resolveUrl('images/bg.png?v=123#section', mockBaseFileUrl);
+        // The path used to *fetch* the asset should NOT have the query/fragment
+        const expectedBgFetchPath = normalizePath(filePaths.bgImage);
+        // Define expected assets
+        const expectedAssets: ExpectedAsset[] = [
+            { type: 'css', url: expectedCssUrl, content: expect.stringContaining('images/bg.png?v=123#section') }, // CSS content as text
+            { type: 'image', url: expectedBgUrlWithQuery, content: expect.stringMatching(/^data:image\/png;base64,/) } // Image as data URI
+        ];
+        // Assert results
+        expectAssetsToContain(result.assets, expectedAssets);
+        // *** CORRECTED EXPECTATION ***: Check that the correct files were read (with only one argument)
+        expect(mockReadFile).toHaveBeenCalledWith(normalizePath(filePaths.complexUrlCss));
+        // *** CORRECTED EXPECTATION ***: Verify the *fetch path* was used (with only one argument)
+        expect(mockReadFile).toHaveBeenCalledWith(expectedBgFetchPath);
+    });
 
-    it('🛑 hits iteration limit if asset queue keeps growing (logs error)', async () => {
-        let counter = 0; const generateUniqueUrl = (baseUrl: string) => `generated_${counter++}.css`;
-        mockedReadFile.mockImplementation(async (p) => { const requestingUrl = p instanceof URL ? p.href : p.toString(); let baseUrlForNesting = mockBaseUrlFile; if (requestingUrl.startsWith('file:')) { try { baseUrlForNesting = new URL('.', requestingUrl).href; } catch {} } const nextUniqueRelativeUrl = generateUniqueUrl(requestingUrl); return Buffer.from(`@import url("${nextUniqueRelativeUrl}"); /* Cycle ${counter} */`); });
-        const parsed: ParsedHTML = { htmlContent: ``, assets: [{ type: 'css', url: 'start.css' }] };
-        await extractAssets(parsed, true, mockBaseDir, mockLogger);
-        // --- Verify Logging ---
-        expect(mockLoggerErrorSpy).toHaveBeenCalled(); // <-- Corrected Expectation (don't check times=1)
-        expect(mockLoggerErrorSpy).toHaveBeenCalledWith(expect.stringContaining("🛑 Asset extraction loop limit hit (1000)!"));
-        // --- Verify Mock Calls ---
-        expect(mockedReadFile.mock.calls.length).toBeGreaterThanOrEqual(1000); expect(mockedReadFile.mock.calls.length).toBeLessThan(1010);
+    it('should properly resolve protocol-relative URLs using the base URL protocol', async () => {
+        // Define an HTTPS base URL for the HTML
+        const htmlBase = 'https://mysite.com/page.html';
+        // HTML contains a protocol-relative script URL (starts with //)
+        const parsed: ParsedHTML = { htmlContent: '<script src="//example.com/js/lib.js"></script>', assets: [{ type: 'js', url: '//example.com/js/lib.js' }] };
+        // Call extractor
+        const result = await extractAssets(parsed, true, htmlBase, mockLogger);
+        // Expect the protocol-relative URL to be resolved using the base URL's protocol (https)
+        const expectedUrl = 'https://example.com/js/lib.js';
+        // Define expected assets
+        const expectedAssets: ExpectedAsset[] = [
+            { type: 'js', url: expectedUrl, content: 'console.log("remote lib");' } // Content comes from Axios mock
+        ];
+        // Assert results
+        expectAssetsToContain(result.assets, expectedAssets);
+        // Verify axios was called with the correctly resolved HTTPS URL
+        expect(mockAxiosGet).toHaveBeenCalledWith(expectedUrl, expect.anything());
     });
 
-}); // End describe suite
+}); // End describe block