imgcap 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.0.2](https://github.com/molvqingtai/imgcap/compare/v1.0.1...v1.0.2) (2025-07-14)
+
+
+### Bug Fixes
+
+* optimize result selection logic in compression algorithm ([48505de](https://github.com/molvqingtai/imgcap/commit/48505de64e9d361266c604c92fb9f62c64ba5f75))
+
 ## [1.0.1](https://github.com/molvqingtai/imgcap/compare/v1.0.0...v1.0.1) (2025-07-14)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # ImgCap
 
-Automatically compress images to exact file size using binary search algorithm.
+Automatically compress images to approximate target file size using binary search algorithm.
 
 [![version](https://img.shields.io/github/v/release/molvqingtai/imgcap)](https://www.npmjs.com/package/imgcap) [![workflow](https://github.com/molvqingtai/imgcap/actions/workflows/ci.yml/badge.svg)](https://github.com/molvqingtai/imgcap/actions) [![download](https://img.shields.io/npm/dt/imgcap)](https://www.npmjs.com/package/imgcap) [![npm package minimized gzipped size](https://img.shields.io/bundlejs/size/imgcap)](https://www.npmjs.com/package/imgcap)
 
@@ -8,9 +8,11 @@ Automatically compress images to exact file size using binary search algorithm.
 pnpm install imgcap
 ```
 
-### Why ImgCap?
+### Why?
 
-Users often encounter "File too large" errors when uploading images, forcing them to manually compress files using external tools. This creates friction and leads to user dropout. imgcap solves this by automatically compressing images to exact size requirements - no user intervention needed.
+Users often encounter "File too large" errors when uploading images, forcing them to manually compress files using external tools. This creates friction and leads to user dropout. imgcap solves this by automatically compressing images to approximate your target size - no user intervention needed.
+
+**Note**: The `targetSize` represents an ideal target. The actual output size will approximate this value within a reasonable tolerance range for optimal performance.
 
 ```typescript
 // Before: User sees error, leaves frustrated
@@ -39,14 +41,28 @@ const webp = await imgcap(imageFile, {
 
 ```typescript
 interface Options {
-  targetSize: number // Target file size in bytes
-  toleranceSize?: number // Size tolerance (default: -1024)
+  targetSize: number // Target file size in bytes (approximate)
   outputType?: ImageType // Output format (default: same as input)
 }
 
 type ImageType = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif'
 ```
 
+#### Tolerance Behavior
+
+The algorithm automatically applies smart tolerance based on target size:
+
+- **Small files** (<100KB): ±1KB tolerance for high precision
+- **Medium files** (100KB-100MB): ±1% tolerance for reasonable flexibility
+- **Large files** (>100MB): ±1MB tolerance to avoid excessive processing
+
+**Examples:**
+
+- Target 50KB → Actual: 49-51KB
+- Target 500KB → Actual: 495-505KB
+- Target 50MB → Actual: 49.5-50.5MB
+- Target 1GB → Actual: 1023-1025MB
+
 **Browser only** - Requires OffscreenCanvas support (modern browsers).
 
 ### License

package/__tests__/package.json

@@ -1,7 +1,7 @@
 {
   "name": "__tests__",
   "version": "1.0.0",
-  "description": "Automatically compress images to exact file size using binary search algorithm.",
+  "description": "Automatically compress images to approximate target file size using binary search algorithm.",
   "main": "index.js",
   "scripts": {
     "test": "vitest --browser.headless",

package/__tests__/unit/imgcap.test.ts

@@ -18,28 +18,26 @@ describe('imgcap', () => {
       )
     })
 
-    it('should throw error for tolerance size less than 1024', async () => {
-      await expect(imgcap(testImageBlob, { targetSize: 10000, toleranceSize: 512 })).rejects.toThrow(
-        'Tolerance size must be at least ±1024 bytes.'
+    it('should throw error for zero target size', async () => {
+      await expect(imgcap(testImageBlob, { targetSize: 0 })).rejects.toThrow(
+        'Target size must be at least 1KB (1024 bytes).'
       )
     })
 
-    it('should throw error for negative tolerance size less than -1024', async () => {
-      await expect(imgcap(testImageBlob, { targetSize: 10000, toleranceSize: -512 })).rejects.toThrow(
-        'Tolerance size must be at least ±1024 bytes.'
+    it('should throw error for negative target size', async () => {
+      await expect(imgcap(testImageBlob, { targetSize: -1000 })).rejects.toThrow(
+        'Target size must be at least 1KB (1024 bytes).'
       )
     })
 
-    it('should accept tolerance size of exactly ±1024', async () => {
-      await expect(imgcap(testImageBlob, { targetSize: 10000, toleranceSize: 1024 })).resolves.toBeDefined()
-
-      await expect(imgcap(testImageBlob, { targetSize: 10000, toleranceSize: -1024 })).resolves.toBeDefined()
+    it('should throw error for target size less than 1KB', async () => {
+      await expect(imgcap(testImageBlob, { targetSize: 512 })).rejects.toThrow(
+        'Target size must be at least 1KB (1024 bytes).'
+      )
     })
 
-    it('should accept tolerance size greater than ±1024', async () => {
-      await expect(imgcap(testImageBlob, { targetSize: 10000, toleranceSize: 2048 })).resolves.toBeDefined()
-
-      await expect(imgcap(testImageBlob, { targetSize: 10000, toleranceSize: -2048 })).resolves.toBeDefined()
+    it('should accept target size of exactly 1KB', async () => {
+      await expect(imgcap(testImageBlob, { targetSize: 1024 })).resolves.toBeDefined()
     })
   })
 
@@ -53,36 +51,21 @@ describe('imgcap', () => {
     })
 
     it('should compress image to approximate target size', async () => {
-      const targetSize = 5000
-      const result = await imgcap(testImageBlob, {
-        targetSize,
-        toleranceSize: -1024
-      })
+      const targetSize = 5000 // Use 5KB target to force compression
+      const result = await imgcap(testImageBlob, { targetSize })
 
       expect(result).toBeInstanceOf(Blob)
-      expect(result.size).toBeLessThanOrEqual(targetSize)
-      // 允许更大的容差范围，因为压缩算法可能产生更小的文件
-      expect(result.size).toBeGreaterThan(500)
+      expect(result.size).toBeLessThanOrEqual(targetSize + 2000) // Allow reasonable tolerance
     })
 
-    it('should respect tolerance range', async () => {
-      const targetSize = 3000
-      const toleranceSize = -1024
-      const result = await imgcap(testImageBlob, {
-        targetSize,
-        toleranceSize
-      })
-
-      const lowerBound = targetSize + Math.min(0, toleranceSize)
-      const upperBound = targetSize + Math.max(0, toleranceSize)
+    it('should produce reasonably sized output', async () => {
+      // Test that algorithm produces reasonable results
+      const targetSize = 3000 // Use 3KB target
+      const result = await imgcap(testImageBlob, { targetSize })
 
-      expect(result.size).toBeLessThanOrEqual(upperBound)
-      // 对于负容差，只检查上界，因为压缩可能产生比期望更小的文件
-      if (toleranceSize < 0) {
-        expect(result.size).toBeGreaterThan(500) // 确保不会过小
-      } else {
-        expect(result.size).toBeGreaterThanOrEqual(lowerBound)
-      }
+      expect(result).toBeInstanceOf(Blob)
+      expect(result.size).toBeLessThanOrEqual(targetSize + 1000) // Allow tolerance
+      expect(result.size).toBeGreaterThan(1000) // Should not be too small
     })
   })
 
@@ -125,24 +108,20 @@ describe('imgcap', () => {
 
     it('should handle very small target sizes', async () => {
       const targetSize = 2000
-      const result = await imgcap(testImageBlob, {
-        targetSize,
-        toleranceSize: -1024
-      })
+      const result = await imgcap(testImageBlob, { targetSize })
 
-      expect(result.size).toBeLessThanOrEqual(targetSize)
+      expect(result.size).toBeLessThanOrEqual(targetSize + 1024) // Within 1KB tolerance for small files
       expect(result.size).toBeGreaterThan(500) // Should not be too small
     })
 
-    it('should handle edge case with very large tolerance', async () => {
-      const targetSize = 5000
-      const toleranceSize = 10000
-      const result = await imgcap(testImageBlob, {
-        targetSize,
-        toleranceSize
-      })
+    it('should handle large target sizes gracefully', async () => {
+      const largeBlob = await createTestImageBlob(400, 300, 'image/png')
+      const targetSize = 50 * 1024 * 1024 // 50MB (unrealistically large for test image)
+      const result = await imgcap(largeBlob, { targetSize })
 
-      expect(result.size).toBeLessThanOrEqual(targetSize + toleranceSize)
+      // Since test image can't be compressed to 50MB, it should return the best possible result
+      expect(result).toBeInstanceOf(Blob)
+      expect(result.size).toBeLessThanOrEqual(targetSize) // Should not exceed target
     })
   })
 

package/__tests__/utils/index.ts

@@ -4,15 +4,30 @@ import { type ImageType } from 'imgcap'
 export const createTestImageBlob = async (width: number = 100, height: number = 100, type: ImageType = 'image/png') => {
   const canvas = new OffscreenCanvas(width, height)
   const ctx = canvas.getContext('2d')!
-  // Draw a simple pattern
+
+  // Fill with white background first
+  ctx.fillStyle = '#ffffff'
+  ctx.fillRect(0, 0, width, height)
+
+  // Create colorful quadrant pattern for better compression testing
+  const halfWidth = width / 2
+  const halfHeight = height / 2
+
+  // Top-left: Red
   ctx.fillStyle = '#ff0000'
-  ctx.fillRect(0, 0, width / 2, height / 2)
+  ctx.fillRect(0, 0, halfWidth, halfHeight)
+
+  // Top-right: Green
   ctx.fillStyle = '#00ff00'
-  ctx.fillRect(width / 2, 0, width / 2, height / 2)
+  ctx.fillRect(halfWidth, 0, halfWidth, halfHeight)
+
+  // Bottom-left: Blue
   ctx.fillStyle = '#0000ff'
-  ctx.fillRect(0, height / 2, width / 2, height / 2)
+  ctx.fillRect(0, halfHeight, halfWidth, halfHeight)
+
+  // Bottom-right: Yellow
   ctx.fillStyle = '#ffff00'
-  ctx.fillRect(width / 2, height / 2, width / 2, height / 2)
+  ctx.fillRect(halfWidth, halfHeight, halfWidth, halfHeight)
 
   return await canvas.convertToBlob({ type })
 }

package/core/dist/index.d.ts

@@ -3,30 +3,35 @@
 type ImageType = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif';
 /** Compression options */
 interface Options {
-  /** Target file size in bytes */
+  /** Target file size in bytes (result will approximate this value) */
   targetSize: number;
-  /** Size tolerance in bytes (default: -1024) */
-  toleranceSize?: number;
   /** Output image format (default: same as input) */
   outputType?: ImageType;
 }
 /**
- * Compress an image to exact target file size using binary search algorithm.
+ * Compress an image to approximate target file size using binary search algorithm.
+ *
+ * The actual output size will be close to the target size within a smart tolerance range:
+ * - Small files (<100KB): ±1KB tolerance
+ * - Medium files (100KB-100MB): ±1% tolerance
+ * - Large files (>100MB): ±1MB tolerance
  *
  * @param input - Image blob/file to compress
- * @param options - Compression options
+ * @param options - Compression options with targetSize as approximate target
  * @returns Promise that resolves to compressed image blob
  *
  * @example
  * ```typescript
- * // Basic usage - compress to 500KB
+ * // Basic usage - compress to approximately 500KB
  * const compressed = await imgcap(imageFile, { targetSize: 500 * 1024 })
+ * // Result: ~495-505KB depending on image characteristics
  *
  * // With format conversion
  * const webp = await imgcap(imageFile, {
  *   targetSize: 300 * 1024,
  *   outputType: 'image/webp'
  * })
+ * // Result: ~297-303KB in WebP format
  * ```
  */
 declare const imgcap: (input: Blob, options: Options) => Promise<Blob>;

package/core/dist/index.js

@@ -1,2 +1,2 @@
-const e=async(t,n,r,i,a,o)=>{let s=(r+i)/2,c=Math.round(t.width*s),l=Math.round(t.height*s),u=new OffscreenCanvas(c,l),d=u.getContext(`2d`);d.drawImage(t,0,0,t.width,t.height,0,0,c,l);let f=await u.convertToBlob({type:o,quality:s}),p=f.size,m=n+Math.min(0,a),h=n+Math.max(0,a);return p>=m&&p<=h||(i-r)/i<.001?f:p>n?await e(t,n,r,s,a,o):await e(t,n,s,i,a,o)},t=async(t,n)=>{let{targetSize:r,toleranceSize:i=-1024}=n;if(![`image/jpeg`,`image/png`,`image/webp`,`image/avif`].includes(t.type))throw Error(`Only PNG, JPEG, WebP and AVIF images are supported.`);if(Math.abs(i)<1024)throw Error(`Tolerance size must be at least ±1024 bytes.`);let a=n.outputType||t.type;if(t.size<=r&&t.type===a)return t;let o=await createImageBitmap(t),s=0,c=1;return await e(o,r,s,c,i,a)};var n=t;export{n as default,t as imgcap};
+const e=async(t,n,r,i,a,o)=>{let s=(r+i)/2,c=Math.round(t.width*s),l=Math.round(t.height*s),u=new OffscreenCanvas(c,l),d=u.getContext(`2d`);d.drawImage(t,0,0,t.width,t.height,0,0,c,l);let f=await u.convertToBlob({type:a,quality:s}),p=f.size;if((!o||Math.abs(p-n)<Math.abs(o.size-n))&&(o=f),(i-r)/i<.01)return o;let m=Math.min(Math.max(1024,n*.01),1024*1024);return Math.abs(p-n)<=m?Math.abs(p-n)<=Math.abs(o.size-n)?f:o:p>n?await e(t,n,r,s,a,o):await e(t,n,s,i,a,o)},t=async(t,n)=>{let{targetSize:r}=n;if(![`image/jpeg`,`image/png`,`image/webp`,`image/avif`].includes(t.type))throw Error(`Only PNG, JPEG, WebP and AVIF images are supported.`);if(r<1024)throw Error(`Target size must be at least 1KB (1024 bytes).`);let i=n.outputType||t.type;if(t.size<=r&&t.type===i)return t;let a=await createImageBitmap(t),o=0,s=1;return await e(a,r,o,s,i)};var n=t;export{n as default,t as imgcap};
 //# sourceMappingURL=index.js.map

package/core/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["imageBitmap: ImageBitmap","targetSize: number","low: number","high: number","toleranceSize: number","outputType: ImageType","input: Blob","options: Options"],"sources":["../src/index.ts"],"sourcesContent":["/** Supported image formats */\nexport type ImageType = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif'\n\n/** Compression options */\nexport interface Options {\n  /** Target file size in bytes */\n  targetSize: number\n  /** Size tolerance in bytes (default: -1024) */\n  toleranceSize?: number\n  /** Output image format (default: same as input) */\n  outputType?: ImageType\n}\n\nconst compress = async (\n  imageBitmap: ImageBitmap,\n  targetSize: number,\n  low: number,\n  high: number,\n  toleranceSize: number,\n  outputType: ImageType\n): Promise<Blob> => {\n  // Calculate the middle quality value\n  const mid = (low + high) / 2\n\n  // Calculate the width and height after scaling\n  const width = Math.round(imageBitmap.width * mid)\n  const height = Math.round(imageBitmap.height * mid)\n\n  const offscreenCanvas = new OffscreenCanvas(width, height)\n  const offscreenContext = offscreenCanvas.getContext('2d')!\n\n  // Draw the scaled image\n  offscreenContext.drawImage(imageBitmap, 0, 0, imageBitmap.width, imageBitmap.height, 0, 0, width, height)\n\n  const outputBlob = await offscreenCanvas.convertToBlob({ type: outputType, quality: mid })\n\n  const currentSize = outputBlob.size\n\n  // Check if current size is within tolerance range\n  const lowerBound = targetSize + Math.min(0, toleranceSize)\n  const upperBound = targetSize + Math.max(0, toleranceSize)\n\n  if (currentSize >= lowerBound && currentSize <= upperBound) {\n    return outputBlob\n  }\n\n  // Use relative error\n  if ((high - low) / high < 0.001) {\n    return outputBlob\n  }\n\n  if (currentSize > targetSize) {\n    return await compress(imageBitmap, targetSize, low, mid, toleranceSize, outputType)\n  } else {\n    return await compress(imageBitmap, targetSize, mid, high, toleranceSize, outputType)\n  }\n}\n\n/**\n * Compress an image to exact target file size using binary search algorithm.\n *\n * @param input - Image blob/file to compress\n * @param options - Compression options\n * @returns Promise that resolves to compressed image blob\n *\n * @example\n * ```typescript\n * // Basic usage - compress to 500KB\n * const compressed = await imgcap(imageFile, { targetSize: 500 * 1024 })\n *\n * // With format conversion\n * const webp = await imgcap(imageFile, {\n *   targetSize: 300 * 1024,\n *   outputType: 'image/webp'\n * })\n * ```\n */\nexport const imgcap = async (input: Blob, options: Options) => {\n  const { targetSize, toleranceSize = -1024 } = options\n\n  if (!['image/jpeg', 'image/png', 'image/webp', 'image/avif'].includes(input.type)) {\n    throw new Error('Only PNG, JPEG, WebP and AVIF images are supported.')\n  }\n\n  if (Math.abs(toleranceSize) < 1024) {\n    throw new Error('Tolerance size must be at least ±1024 bytes.')\n  }\n\n  const outputType = options.outputType || (input.type as ImageType)\n\n  if (input.size <= targetSize && input.type === outputType) {\n    return input\n  }\n\n  const imageBitmap = await createImageBitmap(input)\n\n  // Initialize quality range\n  const low = 0\n  const high = 1\n\n  return await compress(imageBitmap, targetSize, low, high, toleranceSize, outputType)\n}\n\nexport default imgcap\n"],"mappings":"AAaA,MAAM,EAAW,MACfA,EACAC,EACAC,EACAC,EACAC,EACAC,IACkB,CAElB,IAAM,GAAO,EAAM,GAAQ,EAGrB,EAAQ,KAAK,MAAM,EAAY,MAAQ,EAAI,CAC3C,EAAS,KAAK,MAAM,EAAY,OAAS,EAAI,CAE7C,EAAkB,IAAI,gBAAgB,EAAO,GAC7C,EAAmB,EAAgB,WAAW,KAAK,CAGzD,EAAiB,UAAU,EAAa,EAAG,EAAG,EAAY,MAAO,EAAY,OAAQ,EAAG,EAAG,EAAO,EAAO,CAEzG,IAAM,EAAa,KAAM,GAAgB,cAAc,CAAE,KAAM,EAAY,QAAS,CAAK,EAAC,CAEpF,EAAc,EAAW,KAGzB,EAAa,EAAa,KAAK,IAAI,EAAG,EAAc,CACpD,EAAa,EAAa,KAAK,IAAI,EAAG,EAAc,CAcxD,OAZE,GAAe,GAAc,GAAe,IAK3C,EAAO,GAAO,EAAO,KACjB,EAGL,EAAc,EACT,KAAM,GAAS,EAAa,EAAY,EAAK,EAAK,EAAe,EAAW,CAE5E,KAAM,GAAS,EAAa,EAAY,EAAK,EAAM,EAAe,EAAW,AAEvF,EAqBY,EAAS,MAAOC,EAAaC,IAAqB,CAC7D,GAAM,CAAE,aAAY,gBAAgB,MAAO,CAAG,EAE9C,IAAK,CAAC,aAAc,YAAa,aAAc,YAAa,EAAC,SAAS,EAAM,KAAK,CAC/E,KAAM,CAAI,MAAM,sDAAA,CAGlB,GAAI,KAAK,IAAI,EAAc,CAAG,KAC5B,KAAM,CAAI,MAAM,+CAAA,CAGlB,IAAM,EAAa,EAAQ,YAAe,EAAM,KAEhD,GAAI,EAAM,MAAQ,GAAc,EAAM,OAAS,EAC7C,OAAO,EAGT,IAAM,EAAc,KAAM,mBAAkB,EAAM,CAG5C,EAAM,EACN,EAAO,EAEb,OAAO,KAAM,GAAS,EAAa,EAAY,EAAK,EAAM,EAAe,EAAW,AACrF,EAED,IAAA,EAAe"}
+{"version":3,"file":"index.js","names":["imageBitmap: ImageBitmap","targetSize: number","low: number","high: number","outputType: ImageType","bestBlob?: Blob","input: Blob","options: Options"],"sources":["../src/index.ts"],"sourcesContent":["/** Supported image formats */\nexport type ImageType = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif'\n\n/** Compression options */\nexport interface Options {\n  /** Target file size in bytes (result will approximate this value) */\n  targetSize: number\n  /** Output image format (default: same as input) */\n  outputType?: ImageType\n}\n\nconst compress = async (\n  imageBitmap: ImageBitmap,\n  targetSize: number,\n  low: number,\n  high: number,\n  outputType: ImageType,\n  bestBlob?: Blob\n): Promise<Blob> => {\n  // Calculate the middle quality value\n  const mid = (low + high) / 2\n\n  // Calculate the width and height after scaling\n  const width = Math.round(imageBitmap.width * mid)\n  const height = Math.round(imageBitmap.height * mid)\n\n  const offscreenCanvas = new OffscreenCanvas(width, height)\n  const offscreenContext = offscreenCanvas.getContext('2d')!\n\n  // Draw the scaled image\n  offscreenContext.drawImage(imageBitmap, 0, 0, imageBitmap.width, imageBitmap.height, 0, 0, width, height)\n\n  const outputBlob = await offscreenCanvas.convertToBlob({ type: outputType, quality: mid })\n\n  const currentSize = outputBlob.size\n\n  // Update best result - track the closest to target size\n  if (!bestBlob || Math.abs(currentSize - targetSize) < Math.abs(bestBlob.size - targetSize)) {\n    bestBlob = outputBlob\n  }\n\n  // Precision limit reached - return best result\n  if ((high - low) / high < 0.01) {\n    return bestBlob\n  }\n\n  // Check if we hit the target exactly or very close\n  // Dynamic tolerance: 1KB or 1% of target size (whichever is larger), capped at 1MB\n  // - Small files (<100KB): 1KB tolerance for high precision\n  // - Medium files (100KB-100MB): 1% tolerance for reasonable flexibility\n  // - Large files (>100MB): 1MB tolerance to avoid excessive iterations\n  const tolerance = Math.min(Math.max(1024, targetSize * 0.01), 1024 * 1024)\n  if (Math.abs(currentSize - targetSize) <= tolerance) {\n    // Return the result that's closest to target size\n    return Math.abs(currentSize - targetSize) <= Math.abs(bestBlob.size - targetSize) ? outputBlob : bestBlob\n  }\n\n  if (currentSize > targetSize) {\n    return await compress(imageBitmap, targetSize, low, mid, outputType, bestBlob)\n  } else {\n    return await compress(imageBitmap, targetSize, mid, high, outputType, bestBlob)\n  }\n}\n\n/**\n * Compress an image to approximate target file size using binary search algorithm.\n *\n * The actual output size will be close to the target size within a smart tolerance range:\n * - Small files (<100KB): ±1KB tolerance\n * - Medium files (100KB-100MB): ±1% tolerance\n * - Large files (>100MB): ±1MB tolerance\n *\n * @param input - Image blob/file to compress\n * @param options - Compression options with targetSize as approximate target\n * @returns Promise that resolves to compressed image blob\n *\n * @example\n * ```typescript\n * // Basic usage - compress to approximately 500KB\n * const compressed = await imgcap(imageFile, { targetSize: 500 * 1024 })\n * // Result: ~495-505KB depending on image characteristics\n *\n * // With format conversion\n * const webp = await imgcap(imageFile, {\n *   targetSize: 300 * 1024,\n *   outputType: 'image/webp'\n * })\n * // Result: ~297-303KB in WebP format\n * ```\n */\nexport const imgcap = async (input: Blob, options: Options) => {\n  const { targetSize } = options\n\n  if (!['image/jpeg', 'image/png', 'image/webp', 'image/avif'].includes(input.type)) {\n    throw new Error('Only PNG, JPEG, WebP and AVIF images are supported.')\n  }\n\n  if (targetSize < 1024) {\n    throw new Error('Target size must be at least 1KB (1024 bytes).')\n  }\n\n  const outputType = options.outputType || (input.type as ImageType)\n\n  if (input.size <= targetSize && input.type === outputType) {\n    return input\n  }\n\n  const imageBitmap = await createImageBitmap(input)\n\n  // Initialize quality range\n  const low = 0\n  const high = 1\n\n  return await compress(imageBitmap, targetSize, low, high, outputType)\n}\n\nexport default imgcap\n"],"mappings":"AAWA,MAAM,EAAW,MACfA,EACAC,EACAC,EACAC,EACAC,EACAC,IACkB,CAElB,IAAM,GAAO,EAAM,GAAQ,EAGrB,EAAQ,KAAK,MAAM,EAAY,MAAQ,EAAI,CAC3C,EAAS,KAAK,MAAM,EAAY,OAAS,EAAI,CAE7C,EAAkB,IAAI,gBAAgB,EAAO,GAC7C,EAAmB,EAAgB,WAAW,KAAK,CAGzD,EAAiB,UAAU,EAAa,EAAG,EAAG,EAAY,MAAO,EAAY,OAAQ,EAAG,EAAG,EAAO,EAAO,CAEzG,IAAM,EAAa,KAAM,GAAgB,cAAc,CAAE,KAAM,EAAY,QAAS,CAAK,EAAC,CAEpF,EAAc,EAAW,KAQ/B,KALK,GAAY,KAAK,IAAI,EAAc,EAAW,CAAG,KAAK,IAAI,EAAS,KAAO,EAAW,IACxF,EAAW,IAIR,EAAO,GAAO,EAAO,IACxB,OAAO,EAQT,IAAM,EAAY,KAAK,IAAI,KAAK,IAAI,KAAM,EAAa,IAAK,CAAE,KAAO,KAAK,CASxE,MARE,MAAK,IAAI,EAAc,EAAW,EAAI,EAEjC,KAAK,IAAI,EAAc,EAAW,EAAI,KAAK,IAAI,EAAS,KAAO,EAAW,CAAG,EAAa,EAG/F,EAAc,EACT,KAAM,GAAS,EAAa,EAAY,EAAK,EAAK,EAAY,EAAS,CAEvE,KAAM,GAAS,EAAa,EAAY,EAAK,EAAM,EAAY,EAAS,AAElF,EA4BY,EAAS,MAAOC,EAAaC,IAAqB,CAC7D,GAAM,CAAE,aAAY,CAAG,EAEvB,IAAK,CAAC,aAAc,YAAa,aAAc,YAAa,EAAC,SAAS,EAAM,KAAK,CAC/E,KAAM,CAAI,MAAM,sDAAA,CAGlB,GAAI,EAAa,KACf,KAAM,CAAI,MAAM,iDAAA,CAGlB,IAAM,EAAa,EAAQ,YAAe,EAAM,KAEhD,GAAI,EAAM,MAAQ,GAAc,EAAM,OAAS,EAC7C,OAAO,EAGT,IAAM,EAAc,KAAM,mBAAkB,EAAM,CAG5C,EAAM,EACN,EAAO,EAEb,OAAO,KAAM,GAAS,EAAa,EAAY,EAAK,EAAM,EAAW,AACtE,EAED,IAAA,EAAe"}

package/core/package.json

@@ -1,7 +1,7 @@
 {
   "name": "core",
   "version": "1.0.0",
-  "description": "Automatically compress images to exact file size using binary search algorithm.",
+  "description": "Automatically compress images to approximate target file size using binary search algorithm.",
   "main": "dist/index.js",
   "type": "module",
   "scripts": {

package/core/src/index.ts

@@ -3,10 +3,8 @@ export type ImageType = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif'
 
 /** Compression options */
 export interface Options {
-  /** Target file size in bytes */
+  /** Target file size in bytes (result will approximate this value) */
   targetSize: number
-  /** Size tolerance in bytes (default: -1024) */
-  toleranceSize?: number
   /** Output image format (default: same as input) */
   outputType?: ImageType
 }
@@ -16,8 +14,8 @@ const compress = async (
   targetSize: number,
   low: number,
   high: number,
-  toleranceSize: number,
-  outputType: ImageType
+  outputType: ImageType,
+  bestBlob?: Blob
 ): Promise<Blob> => {
   // Calculate the middle quality value
   const mid = (low + high) / 2
@@ -36,54 +34,69 @@ const compress = async (
 
   const currentSize = outputBlob.size
 
-  // Check if current size is within tolerance range
-  const lowerBound = targetSize + Math.min(0, toleranceSize)
-  const upperBound = targetSize + Math.max(0, toleranceSize)
+  // Update best result - track the closest to target size
+  if (!bestBlob || Math.abs(currentSize - targetSize) < Math.abs(bestBlob.size - targetSize)) {
+    bestBlob = outputBlob
+  }
 
-  if (currentSize >= lowerBound && currentSize <= upperBound) {
-    return outputBlob
+  // Precision limit reached - return best result
+  if ((high - low) / high < 0.01) {
+    return bestBlob
   }
 
-  // Use relative error
-  if ((high - low) / high < 0.001) {
-    return outputBlob
+  // Check if we hit the target exactly or very close
+  // Dynamic tolerance: 1KB or 1% of target size (whichever is larger), capped at 1MB
+  // - Small files (<100KB): 1KB tolerance for high precision
+  // - Medium files (100KB-100MB): 1% tolerance for reasonable flexibility
+  // - Large files (>100MB): 1MB tolerance to avoid excessive iterations
+  const tolerance = Math.min(Math.max(1024, targetSize * 0.01), 1024 * 1024)
+  if (Math.abs(currentSize - targetSize) <= tolerance) {
+    // Return the result that's closest to target size
+    return Math.abs(currentSize - targetSize) <= Math.abs(bestBlob.size - targetSize) ? outputBlob : bestBlob
   }
 
   if (currentSize > targetSize) {
-    return await compress(imageBitmap, targetSize, low, mid, toleranceSize, outputType)
+    return await compress(imageBitmap, targetSize, low, mid, outputType, bestBlob)
   } else {
-    return await compress(imageBitmap, targetSize, mid, high, toleranceSize, outputType)
+    return await compress(imageBitmap, targetSize, mid, high, outputType, bestBlob)
   }
 }
 
 /**
- * Compress an image to exact target file size using binary search algorithm.
+ * Compress an image to approximate target file size using binary search algorithm.
+ *
+ * The actual output size will be close to the target size within a smart tolerance range:
+ * - Small files (<100KB): ±1KB tolerance
+ * - Medium files (100KB-100MB): ±1% tolerance
+ * - Large files (>100MB): ±1MB tolerance
  *
  * @param input - Image blob/file to compress
- * @param options - Compression options
+ * @param options - Compression options with targetSize as approximate target
  * @returns Promise that resolves to compressed image blob
  *
  * @example
  * ```typescript
- * // Basic usage - compress to 500KB
+ * // Basic usage - compress to approximately 500KB
  * const compressed = await imgcap(imageFile, { targetSize: 500 * 1024 })
+ * // Result: ~495-505KB depending on image characteristics
  *
  * // With format conversion
  * const webp = await imgcap(imageFile, {
  *   targetSize: 300 * 1024,
  *   outputType: 'image/webp'
  * })
+ * // Result: ~297-303KB in WebP format
  * ```
  */
 export const imgcap = async (input: Blob, options: Options) => {
-  const { targetSize, toleranceSize = -1024 } = options
+  const { targetSize } = options
 
   if (!['image/jpeg', 'image/png', 'image/webp', 'image/avif'].includes(input.type)) {
     throw new Error('Only PNG, JPEG, WebP and AVIF images are supported.')
   }
 
-  if (Math.abs(toleranceSize) < 1024) {
-    throw new Error('Tolerance size must be at least ±1024 bytes.')
+  if (targetSize < 1024) {
+    throw new Error('Target size must be at least 1KB (1024 bytes).')
   }
 
   const outputType = options.outputType || (input.type as ImageType)
@@ -98,7 +111,7 @@ export const imgcap = async (input: Blob, options: Options) => {
   const low = 0
   const high = 1
 
-  return await compress(imageBitmap, targetSize, low, high, toleranceSize, outputType)
+  return await compress(imageBitmap, targetSize, low, high, outputType)
 }
 
 export default imgcap

package/index.html

@@ -0,0 +1,479 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>imgcap Demo - Precise Image Compression</title>
+    <script type="importmap">
+      {
+        "imports": {
+          "imgcap": "https://esm.sh/imgcap@latest"
+        }
+      }
+    </script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        min-height: 100vh;
+        padding: 20px;
+      }
+
+      .container {
+        max-width: 800px;
+        margin: 0 auto;
+        background: white;
+        border-radius: 20px;
+        box-shadow: 0 20px 40px rgba(0, 0, 0, 0.1);
+        overflow: hidden;
+      }
+
+      .header {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        color: white;
+        padding: 30px;
+        text-align: center;
+      }
+
+      .header h1 {
+        font-size: 2.5rem;
+        margin-bottom: 10px;
+      }
+
+      .header p {
+        font-size: 1.1rem;
+        opacity: 0.9;
+      }
+
+      .content {
+        padding: 40px;
+      }
+
+      .upload-section {
+        margin-bottom: 40px;
+      }
+
+      .upload-area {
+        border: 3px dashed #ddd;
+        border-radius: 15px;
+        padding: 40px;
+        text-align: center;
+        cursor: pointer;
+        transition: all 0.3s ease;
+        background: #fafafa;
+      }
+
+      .upload-area:hover {
+        border-color: #667eea;
+        background: #f0f4ff;
+      }
+
+      .upload-area.dragover {
+        border-color: #667eea;
+        background: #e8f2ff;
+        transform: scale(1.02);
+      }
+
+      .upload-icon {
+        font-size: 3rem;
+        margin-bottom: 20px;
+        color: #667eea;
+      }
+
+      .upload-text {
+        font-size: 1.2rem;
+        color: #666;
+        margin-bottom: 10px;
+      }
+
+      .upload-hint {
+        font-size: 0.9rem;
+        color: #999;
+      }
+
+      .file-input {
+        display: none;
+      }
+
+      .controls {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        gap: 20px;
+        margin-bottom: 30px;
+      }
+
+      .control-group {
+        background: #f8f9fa;
+        padding: 20px;
+        border-radius: 10px;
+      }
+
+      .control-group label {
+        display: block;
+        font-weight: 600;
+        margin-bottom: 10px;
+        color: #333;
+      }
+
+      .control-group input,
+      .control-group select {
+        width: 100%;
+        padding: 12px;
+        border: 2px solid #e1e5e9;
+        border-radius: 8px;
+        font-size: 1rem;
+        transition: border-color 0.3s ease;
+      }
+
+      .control-group input:focus,
+      .control-group select:focus {
+        outline: none;
+        border-color: #667eea;
+      }
+
+      .compress-btn {
+        width: 100%;
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        color: white;
+        border: none;
+        padding: 15px 30px;
+        font-size: 1.1rem;
+        font-weight: 600;
+        border-radius: 10px;
+        cursor: pointer;
+        transition: transform 0.3s ease;
+        margin-bottom: 30px;
+      }
+
+      .compress-btn:hover:not(:disabled) {
+        transform: translateY(-2px);
+      }
+
+      .compress-btn:disabled {
+        opacity: 0.6;
+        cursor: not-allowed;
+      }
+
+      .results {
+        display: none;
+        background: #f8f9fa;
+        border-radius: 15px;
+        padding: 30px;
+      }
+
+      .results.show {
+        display: block;
+      }
+
+      .result-item {
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        padding: 15px 0;
+        border-bottom: 1px solid #e1e5e9;
+      }
+
+      .result-item:last-child {
+        border-bottom: none;
+      }
+
+      .result-label {
+        font-weight: 600;
+        color: #333;
+      }
+
+      .result-value {
+        color: #667eea;
+        font-weight: 500;
+      }
+
+      .image-preview {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        gap: 20px;
+        margin-top: 20px;
+      }
+
+      .preview-item {
+        text-align: center;
+      }
+
+      .preview-item h4 {
+        margin-bottom: 10px;
+        color: #333;
+      }
+
+      .preview-item img {
+        max-width: 100%;
+        max-height: 200px;
+        border-radius: 10px;
+        box-shadow: 0 5px 15px rgba(0, 0, 0, 0.1);
+      }
+
+      .status {
+        margin: 20px 0;
+        padding: 15px;
+        border-radius: 8px;
+        text-align: center;
+        display: none;
+      }
+
+      .status.show {
+        display: block;
+      }
+
+      .status.loading {
+        background: #e3f2fd;
+        color: #1976d2;
+      }
+
+      .status.success {
+        background: #e8f5e8;
+        color: #2e7d32;
+      }
+
+      .status.error {
+        background: #ffebee;
+        color: #c62828;
+      }
+
+      @media (max-width: 768px) {
+        .controls {
+          grid-template-columns: 1fr;
+        }
+
+        .image-preview {
+          grid-template-columns: 1fr;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="container">
+      <div class="header">
+        <h1>🎯 imgcap Demo</h1>
+        <p>Precisely cap your image size with binary search compression</p>
+      </div>
+
+      <div class="content">
+        <div class="upload-section">
+          <div class="upload-area" id="uploadArea">
+            <div class="upload-icon">📁</div>
+            <div class="upload-text">Drop your image here or click to browse</div>
+            <div class="upload-hint">Supports JPEG, PNG, WebP files</div>
+            <input type="file" class="file-input" id="fileInput" accept="image/*" />
+          </div>
+        </div>
+
+        <div class="controls">
+          <div class="control-group">
+            <label for="targetSize">Target Size (KB)</label>
+            <input type="number" id="targetSize" value="500" min="1" max="10000" />
+          </div>
+          <div class="control-group">
+            <label for="outputFormat">Output Format</label>
+            <select id="outputFormat">
+              <option value="">Same as input</option>
+              <option value="image/jpeg">JPEG</option>
+              <option value="image/png">PNG</option>
+              <option value="image/webp">WebP</option>
+              <option value="image/avif">AVIF</option>
+            </select>
+          </div>
+        </div>
+
+        <button class="compress-btn" id="compressBtn" disabled>🚀 Compress Image</button>
+
+        <div class="status" id="status"></div>
+
+        <div class="results" id="results">
+          <h3>Compression Results</h3>
+          <div class="result-item">
+            <span class="result-label">Original Size:</span>
+            <span class="result-value" id="originalSize">-</span>
+          </div>
+          <div class="result-item">
+            <span class="result-label">Compressed Size:</span>
+            <span class="result-value" id="compressedSize">-</span>
+          </div>
+          <div class="result-item">
+            <span class="result-label">Compression Ratio:</span>
+            <span class="result-value" id="compressionRatio">-</span>
+          </div>
+          <div class="result-item">
+            <span class="result-label">Size Reduction:</span>
+            <span class="result-value" id="sizeReduction">-</span>
+          </div>
+
+          <div class="image-preview">
+            <div class="preview-item">
+              <h4>Original</h4>
+              <img id="originalPreview" alt="Original image" />
+            </div>
+            <div class="preview-item">
+              <h4>Compressed</h4>
+              <img id="compressedPreview" alt="Compressed image" />
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <script type="module">
+      import imgcap from 'imgcap'
+
+      let selectedFile = null
+      let compressedBlob = null
+
+      // DOM elements
+      const uploadArea = document.getElementById('uploadArea')
+      const fileInput = document.getElementById('fileInput')
+      const targetSizeInput = document.getElementById('targetSize')
+      const outputFormatSelect = document.getElementById('outputFormat')
+      const compressBtn = document.getElementById('compressBtn')
+      const status = document.getElementById('status')
+      const results = document.getElementById('results')
+      const originalSizeSpan = document.getElementById('originalSize')
+      const compressedSizeSpan = document.getElementById('compressedSize')
+      const compressionRatioSpan = document.getElementById('compressionRatio')
+      const sizeReductionSpan = document.getElementById('sizeReduction')
+      const originalPreview = document.getElementById('originalPreview')
+      const compressedPreview = document.getElementById('compressedPreview')
+
+      // File upload handlers
+      uploadArea.addEventListener('click', () => fileInput.click())
+      uploadArea.addEventListener('dragover', handleDragOver)
+      uploadArea.addEventListener('dragleave', handleDragLeave)
+      uploadArea.addEventListener('drop', handleDrop)
+      fileInput.addEventListener('change', handleFileSelect)
+      compressBtn.addEventListener('click', compressImage)
+
+      function handleDragOver(e) {
+        e.preventDefault()
+        uploadArea.classList.add('dragover')
+      }
+
+      function handleDragLeave(e) {
+        e.preventDefault()
+        uploadArea.classList.remove('dragover')
+      }
+
+      function handleDrop(e) {
+        e.preventDefault()
+        uploadArea.classList.remove('dragover')
+        const files = e.dataTransfer.files
+        if (files.length > 0) {
+          handleFile(files[0])
+        }
+      }
+
+      function handleFileSelect(e) {
+        const files = e.target.files
+        if (files.length > 0) {
+          handleFile(files[0])
+        }
+      }
+
+      function handleFile(file) {
+        if (!file.type.startsWith('image/')) {
+          showStatus('Please select a valid image file', 'error')
+          return
+        }
+
+        selectedFile = file
+
+        // Update upload area
+        uploadArea.innerHTML = `
+                <div class="upload-icon">✅</div>
+                <div class="upload-text">${file.name}</div>
+                <div class="upload-hint">${formatFileSize(file.size)} • Click to change</div>
+            `
+
+        // Enable compress button
+        compressBtn.disabled = false
+
+        // Show original preview
+        const originalUrl = URL.createObjectURL(file)
+        originalPreview.src = originalUrl
+        originalPreview.onload = () => URL.revokeObjectURL(originalUrl)
+
+        // Hide previous results
+        results.classList.remove('show')
+        status.classList.remove('show')
+      }
+
+      async function compressImage() {
+        if (!selectedFile) return
+
+        const targetSize = parseInt(targetSizeInput.value) * 1024 // Convert KB to bytes
+        const outputType = outputFormatSelect.value || undefined
+
+        try {
+          showStatus('🔄 Compressing image...', 'loading')
+          compressBtn.disabled = true
+
+          const compressed = await imgcap(selectedFile, {
+            targetSize,
+            outputType
+          })
+
+          compressedBlob = compressed
+          showResults(selectedFile, compressed)
+          showStatus('✅ Compression completed!', 'success')
+        } catch (error) {
+          console.error('Compression failed:', error)
+          showStatus(`❌ Error: ${error.message}`, 'error')
+        } finally {
+          compressBtn.disabled = false
+        }
+      }
+
+      function showResults(original, compressed) {
+        // Update result values
+        originalSizeSpan.textContent = formatFileSize(original.size)
+        compressedSizeSpan.textContent = formatFileSize(compressed.size)
+
+        const ratio = ((1 - compressed.size / original.size) * 100).toFixed(1)
+        compressionRatioSpan.textContent = `${ratio}%`
+
+        const reduction = formatFileSize(original.size - compressed.size)
+        sizeReductionSpan.textContent = `${reduction} saved`
+
+        // Debug info - log actual bytes
+        console.log('🔍 Debug Info:')
+        console.log(
+          `Target size: ${parseInt(targetSizeInput.value)} KB (${parseInt(targetSizeInput.value) * 1024} bytes)`
+        )
+        console.log(`Actual size: ${formatFileSize(compressed.size)} (${compressed.size} bytes)`)
+        console.log(`Difference: ${compressed.size - parseInt(targetSizeInput.value) * 1024} bytes`)
+
+        // Show compressed preview
+        const compressedUrl = URL.createObjectURL(compressed)
+        compressedPreview.src = compressedUrl
+        compressedPreview.onload = () => URL.revokeObjectURL(compressedUrl)
+
+        // Show results section
+        results.classList.add('show')
+      }
+
+      function showStatus(message, type) {
+        status.textContent = message
+        status.className = `status show ${type}`
+      }
+
+      function formatFileSize(bytes) {
+        if (bytes === 0) return '0 Bytes'
+        const k = 1024
+        const sizes = ['Bytes', 'KB', 'MB', 'GB']
+        const i = Math.floor(Math.log(bytes) / Math.log(k))
+        return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i]
+      }
+    </script>
+  </body>
+</html>

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "imgcap",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Automatically compress images to exact file size using binary search algorithm.",
   "type": "module",
   "main": "core/dist/index.js",
   "scripts": {
     "dev": "pnpm --filter core dev",
     "build": "pnpm --filter core build",
+    "serve": "serve",
     "lint": "npm-run-all -p lint:*",
     "check": "npm-run-all -p check:*",
     "test": "pnpm --filter __tests__ test",
@@ -52,7 +53,8 @@
     "@semantic-release/git": "^10.0.1",
     "husky": "^9.1.7",
     "npm-run-all": "^4.1.5",
-    "semantic-release": "^24.2.7"
+    "semantic-release": "^24.2.7",
+    "serve": "^14.2.4"
   },
   "publishConfig": {
     "access": "public"