@qvac/ocr-ggml 0.0.1 → 0.1.1

package/test/integration/doctr-param-validation.test.js

@@ -0,0 +1,83 @@
+'use strict'
+
+const { OcrGgml, QvacErrorAddonOcrGgml, ERR_CODES } = require('../..')
+const test = require('brittle')
+const { isMobile, getImagePath, ensureDoctrModels } = require('./utils')
+
+const MOBILE_TIMEOUT = 600 * 1000
+const DESKTOP_TIMEOUT = 30 * 1000
+const TEST_TIMEOUT = isMobile ? MOBILE_TIMEOUT : DESKTOP_TIMEOUT
+
+let DOCTR_DETECTOR
+let DOCTR_RECOGNIZER
+
+test('DocTR param validation - download models', { timeout: 180 * 1000 }, async function (t) {
+  const models = await ensureDoctrModels()
+  DOCTR_DETECTOR = models.db_mobilenet_v3_large
+  DOCTR_RECOGNIZER = models.crnn_mobilenet_v3_small
+  t.ok(DOCTR_DETECTOR, 'db_mobilenet model available')
+  t.ok(DOCTR_RECOGNIZER, 'crnn_mobilenet model available')
+})
+
+test('DocTR load() rejects when pathRecognizer is missing', { timeout: TEST_TIMEOUT }, async function (t) {
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: DOCTR_DETECTOR,
+      langList: ['en'],
+      pipelineType: 'doctr'
+    }
+  })
+
+  try {
+    await ocrGgml.load()
+    t.fail('Should have thrown for missing pathRecognizer in doctr mode')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.MISSING_REQUIRED_PARAMETER, 'Error code should be MISSING_REQUIRED_PARAMETER')
+    t.ok(err.message.includes('pathRecognizer'), 'Error message should mention pathRecognizer')
+    t.pass('Correctly rejected missing pathRecognizer in doctr mode')
+  }
+})
+
+test('DocTR load() rejects when pathDetector is missing', { timeout: TEST_TIMEOUT }, async function (t) {
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathRecognizer: DOCTR_RECOGNIZER,
+      langList: ['en'],
+      pipelineType: 'doctr'
+    }
+  })
+
+  try {
+    await ocrGgml.load()
+    t.fail('Should have thrown for missing pathDetector in doctr mode')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.MISSING_REQUIRED_PARAMETER, 'Error code should be MISSING_REQUIRED_PARAMETER')
+    t.ok(err.message.includes('pathDetector'), 'Error message should mention pathDetector')
+    t.pass('Correctly rejected missing pathDetector in doctr mode')
+  }
+})
+
+test('DocTR run() before load() throws error', { timeout: TEST_TIMEOUT }, async function (t) {
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: DOCTR_DETECTOR,
+      pathRecognizer: DOCTR_RECOGNIZER,
+      langList: ['en'],
+      pipelineType: 'doctr'
+    }
+  })
+
+  try {
+    await ocrGgml.run({
+      path: getImagePath('/test/images/basic_test.bmp'),
+      options: { paragraph: false }
+    })
+    t.fail('Should have thrown when running before load')
+  } catch (err) {
+    t.ok(err, 'Should throw an error when running before load')
+    t.comment('Error: ' + err.message)
+    t.pass('Correctly prevented run before load')
+  }
+})

package/test/integration/error-handling.test.js

@@ -0,0 +1,302 @@
+'use strict'
+
+const { OcrGgml, QvacErrorAddonOcrGgml, ERR_CODES } = require('../..')
+const test = require('brittle')
+const fs = require('bare-fs')
+const path = require('bare-path')
+const { isMobile } = require('./utils')
+
+const MOBILE_TIMEOUT = 600 * 1000
+const DESKTOP_TIMEOUT = 60 * 1000
+const TEST_TIMEOUT = isMobile ? MOBILE_TIMEOUT : DESKTOP_TIMEOUT
+
+const TMP_DIR = isMobile
+  ? path.join(global.testDir || '/tmp', 'test-tmp')
+  : path.resolve('.', 'test', 'tmp')
+
+function setupTmpDir () {
+  if (!fs.existsSync(TMP_DIR)) {
+    fs.mkdirSync(TMP_DIR, { recursive: true })
+  }
+}
+
+function writeTmpFile (name, buffer) {
+  setupTmpDir()
+  const filePath = path.join(TMP_DIR, name)
+  fs.writeFileSync(filePath, buffer)
+  return filePath
+}
+
+function cleanupTmpDir () {
+  if (fs.existsSync(TMP_DIR)) {
+    const files = fs.readdirSync(TMP_DIR)
+    for (const file of files) {
+      fs.unlinkSync(path.join(TMP_DIR, file))
+    }
+    fs.rmdirSync(TMP_DIR)
+  }
+}
+
+function createOcrInstance () {
+  return new OcrGgml({
+    params: {
+      pathDetector: 'models/craft_mlt_25k.gguf',
+      pathRecognizer: 'models/latin_g2.gguf',
+      langList: ['en']
+    }
+  })
+}
+
+// --- Unsupported Image Formats ---
+
+test('_readImage rejects GIF format with UNSUPPORTED_IMAGE_FORMAT', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  // GIF magic bytes: GIF89a
+  const gifBuffer = Buffer.from([0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x01, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00])
+  const filePath = writeTmpFile('test.gif', gifBuffer)
+
+  try {
+    onnxOcr._readImage(filePath)
+    t.fail('Should have thrown for GIF format')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.UNSUPPORTED_IMAGE_FORMAT, 'Error code should be UNSUPPORTED_IMAGE_FORMAT')
+    t.pass('GIF correctly rejected')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+test('_readImage rejects WebP format with UNSUPPORTED_IMAGE_FORMAT', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  // WebP: RIFF....WEBP
+  const webpBuffer = Buffer.alloc(16)
+  webpBuffer.write('RIFF', 0)
+  webpBuffer.writeUInt32LE(8, 4)
+  webpBuffer.write('WEBP', 8)
+  const filePath = writeTmpFile('test.webp', webpBuffer)
+
+  try {
+    onnxOcr._readImage(filePath)
+    t.fail('Should have thrown for WebP format')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.UNSUPPORTED_IMAGE_FORMAT, 'Error code should be UNSUPPORTED_IMAGE_FORMAT')
+    t.pass('WebP correctly rejected')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+test('_readImage rejects TIFF format with UNSUPPORTED_IMAGE_FORMAT', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  // TIFF little-endian: II + 42
+  const tiffBuffer = Buffer.from([0x49, 0x49, 0x2A, 0x00, 0x08, 0x00, 0x00, 0x00])
+  const filePath = writeTmpFile('test.tiff', tiffBuffer)
+
+  try {
+    onnxOcr._readImage(filePath)
+    t.fail('Should have thrown for TIFF format')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.UNSUPPORTED_IMAGE_FORMAT, 'Error code should be UNSUPPORTED_IMAGE_FORMAT')
+    t.pass('TIFF correctly rejected')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+// --- Corrupt / Invalid Image Files ---
+
+test('_readImage rejects zero-byte file', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  const filePath = writeTmpFile('empty.bmp', Buffer.alloc(0))
+
+  try {
+    onnxOcr._readImage(filePath)
+    t.fail('Should have thrown for zero-byte file')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.INVALID_IMAGE_OR_INSUFFICIENT_DATA, 'Error code should be INVALID_IMAGE_OR_INSUFFICIENT_DATA')
+    t.pass('Zero-byte file correctly rejected')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+test('_readImage rejects file with less than 4 bytes', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  const filePath = writeTmpFile('tiny.bin', Buffer.from([0x42, 0x4D, 0x01]))
+
+  try {
+    onnxOcr._readImage(filePath)
+    t.fail('Should have thrown for too-small file')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.INVALID_IMAGE_OR_INSUFFICIENT_DATA, 'Error code should be INVALID_IMAGE_OR_INSUFFICIENT_DATA')
+    t.pass('Too-small file correctly rejected')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+test('_readImage rejects non-existent file', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+
+  try {
+    onnxOcr._readImage('/nonexistent/path/image.bmp')
+    t.fail('Should have thrown for non-existent file')
+  } catch (err) {
+    t.ok(err, 'Should throw an error for non-existent file')
+    t.pass('Non-existent file correctly rejected')
+  }
+})
+
+// --- BMP Parsing Edge Cases ---
+
+test('getImageFromBmp rejects BMP with incomplete header', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  // Valid BMP magic, infoHeaderSize says 40 but buffer is only 24 bytes (< 14 + 40 = 54)
+  const buf = Buffer.alloc(24)
+  buf[0] = 0x42 // B
+  buf[1] = 0x4D // M
+  buf.writeUInt32LE(40, 14) // infoHeaderSize = 40
+  const filePath = writeTmpFile('incomplete_header.bmp', buf)
+
+  try {
+    onnxOcr._readImage(filePath)
+    t.fail('Should have thrown for incomplete BMP header')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.INVALID_IMAGE_OR_INSUFFICIENT_DATA, 'Error code should be INVALID_IMAGE_OR_INSUFFICIENT_DATA')
+    t.pass('Incomplete BMP header correctly rejected')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+test('getImageFromBmp rejects BMP with unsupported header size', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  // BMP magic + infoHeaderSize of 8 (less than minimum 12), buffer must hold at least 14+8=22 bytes
+  const buf = Buffer.alloc(22)
+  buf[0] = 0x42
+  buf[1] = 0x4D
+  buf.writeUInt32LE(8, 14) // infoHeaderSize = 8 (unsupported)
+  const filePath = writeTmpFile('bad_header_size.bmp', buf)
+
+  try {
+    onnxOcr._readImage(filePath)
+    t.fail('Should have thrown for unsupported BMP header size')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.UNSUPPORTED_IMAGE_FORMAT, 'Error code should be UNSUPPORTED_IMAGE_FORMAT')
+    t.pass('Unsupported BMP header size correctly rejected')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+test('getImageFromBmp rejects BMP with truncated pixel data', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  // Valid BMP header for 10x10 24-bit image, but pixel data is incomplete
+  const headerSize = 54
+  const buf = Buffer.alloc(headerSize + 10) // way too little pixel data for 10x10
+  buf[0] = 0x42 // B
+  buf[1] = 0x4D // M
+  buf.writeUInt32LE(headerSize, 10) // pixel data offset
+  buf.writeUInt32LE(40, 14) // infoHeaderSize (BITMAPINFOHEADER)
+  buf.writeInt32LE(10, 18) // width = 10
+  buf.writeInt32LE(10, 22) // height = 10
+  buf.writeUInt16LE(1, 26) // planes
+  buf.writeUInt16LE(24, 28) // bitsPerPixel = 24
+  const filePath = writeTmpFile('truncated_pixels.bmp', buf)
+
+  try {
+    onnxOcr._readImage(filePath)
+    t.fail('Should have thrown for truncated pixel data')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Should throw QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.INVALID_IMAGE_OR_INSUFFICIENT_DATA, 'Error code should be INVALID_IMAGE_OR_INSUFFICIENT_DATA')
+    t.pass('Truncated pixel data correctly rejected')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+test('getImageFromBmp handles negative height (top-down BMP)', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  const width = 2
+  const height = -2 // top-down BMP
+  const bpp = 24
+  const headerSize = 54
+  const rowSize = Math.ceil((width * (bpp / 8)) / 4) * 4
+  const pixelDataSize = Math.abs(height) * rowSize
+  const buf = Buffer.alloc(headerSize + pixelDataSize)
+
+  buf[0] = 0x42
+  buf[1] = 0x4D
+  buf.writeUInt32LE(headerSize, 10)
+  buf.writeUInt32LE(40, 14)
+  buf.writeInt32LE(width, 18)
+  buf.writeInt32LE(height, 22) // negative height
+  buf.writeUInt16LE(1, 26)
+  buf.writeUInt16LE(bpp, 28)
+
+  // Fill pixel data with recognizable pattern
+  for (let i = headerSize; i < buf.length; i++) {
+    buf[i] = i % 256
+  }
+
+  const filePath = writeTmpFile('topdown.bmp', buf)
+
+  try {
+    const result = onnxOcr._readImage(filePath)
+    t.is(result.width, width, 'Width should be 2')
+    t.is(result.height, Math.abs(height), 'Height should be absolute value (2)')
+    t.ok(result.data, 'Should return pixel data buffer')
+    t.ok(result.data.length > 0, 'Pixel data should not be empty')
+    t.pass('Top-down BMP (negative height) parsed successfully')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+test('_readImage correctly detects JPEG by magic bytes', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  // JPEG magic: 0xFF 0xD8
+  const jpegBuffer = Buffer.alloc(16)
+  jpegBuffer[0] = 0xFF
+  jpegBuffer[1] = 0xD8
+  jpegBuffer[2] = 0xFF
+  jpegBuffer[3] = 0xE0
+  const filePath = writeTmpFile('test.jpg', jpegBuffer)
+
+  try {
+    const result = onnxOcr._readImage(filePath)
+    t.ok(result.isEncoded, 'JPEG should be marked as encoded (for C++ decoding)')
+    t.ok(result.data, 'Should contain the raw file data')
+    t.pass('JPEG magic bytes correctly detected')
+  } finally {
+    cleanupTmpDir()
+  }
+})
+
+test('_readImage correctly detects PNG by magic bytes', { timeout: TEST_TIMEOUT }, async function (t) {
+  const onnxOcr = createOcrInstance()
+  // PNG magic: 0x89 0x50 0x4E 0x47
+  const pngBuffer = Buffer.alloc(16)
+  pngBuffer[0] = 0x89
+  pngBuffer[1] = 0x50
+  pngBuffer[2] = 0x4E
+  pngBuffer[3] = 0x47
+  const filePath = writeTmpFile('test.png', pngBuffer)
+
+  try {
+    const result = onnxOcr._readImage(filePath)
+    t.ok(result.isEncoded, 'PNG should be marked as encoded (for C++ decoding)')
+    t.ok(result.data, 'Should contain the raw file data')
+    t.pass('PNG magic bytes correctly detected')
+  } finally {
+    cleanupTmpDir()
+  }
+})

package/test/integration/full-coverage.test.js

@@ -0,0 +1,292 @@
+'use strict'
+
+const { OcrGgml, QvacErrorAddonOcrGgml, ERR_CODES, binding } = require('../..')
+const test = require('brittle')
+const { isMobile, ensureModelPath, getImagePath } = require('./utils')
+
+const MOBILE_TIMEOUT = 600 * 1000
+const DESKTOP_TIMEOUT = 120 * 1000
+const TEST_TIMEOUT = isMobile ? MOBILE_TIMEOUT : DESKTOP_TIMEOUT
+
+function createMinimalOcr () {
+  return new OcrGgml({
+    params: {
+      pathDetector: 'models/craft_mlt_25k.gguf',
+      pathRecognizer: 'models/latin_g2.gguf',
+      langList: ['en']
+    }
+  })
+}
+
+async function loadOcr () {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en']
+    }
+  })
+
+  await ocrGgml.load()
+  return ocrGgml
+}
+
+// =============================================
+// Static methods & properties (index.js)
+// =============================================
+
+test('getModelKey returns ocr-ggml', function (t) {
+  t.is(OcrGgml.getModelKey(), 'ocr-ggml')
+})
+
+test('inferenceManagerConfig.noAdditionalDownload is true', function (t) {
+  t.is(OcrGgml.inferenceManagerConfig.noAdditionalDownload, true)
+})
+
+test('createJobHandler is initialized', function (t) {
+  const ocrGgml = createMinimalOcr()
+  t.ok(ocrGgml._job, 'should have _job handler')
+  t.is(ocrGgml._job.active, null, 'no active response initially')
+})
+
+// =============================================
+// _addonOutputCallback event mapping (index.js)
+// =============================================
+
+test('_addonOutputCallback routes stats object (with totalTime) to _job.end', function (t) {
+  const ocrGgml = createMinimalOcr()
+  ocrGgml.opts = { stats: true }
+
+  // Start a job so there's an active response
+  const response = ocrGgml._job.start()
+  let ended = false
+  let receivedStats = null
+  response.on('stats', s => { receivedStats = s })
+  response.on('end', () => { ended = true })
+
+  const statsData = { totalTime: 1.5, detectionTime: 0.5, recognitionTime: 1.0 }
+  ocrGgml._addonOutputCallback(null, 'SomeMangledType', statsData, null)
+
+  t.ok(ended, 'response should be ended')
+  t.alike(receivedStats, statsData, 'stats should be forwarded')
+  t.is(ocrGgml._job.active, null, 'active response should be cleared')
+})
+
+test('_addonOutputCallback routes Error event to _job.fail', function (t) {
+  const ocrGgml = createMinimalOcr()
+
+  const response = ocrGgml._job.start()
+  let receivedError = null
+  response.onError(err => { receivedError = err })
+
+  ocrGgml._addonOutputCallback(null, 'SomethingError', 'error payload', 'the error')
+
+  t.ok(receivedError, 'error should be received')
+  t.is(ocrGgml._job.active, null, 'active response should be cleared')
+})
+
+test('_addonOutputCallback routes array data to _job.output', function (t) {
+  const ocrGgml = createMinimalOcr()
+
+  const response = ocrGgml._job.start()
+  let receivedData = null
+  response.onUpdate(d => { receivedData = d })
+
+  const outputData = [['box1', 'text1'], ['box2', 'text2']]
+  ocrGgml._addonOutputCallback(null, 'PipelineResult', outputData, null)
+
+  t.alike(receivedData, outputData, 'output data should be routed')
+  t.ok(ocrGgml._job.active, 'active response should still exist (not ended)')
+})
+
+test('_addonOutputCallback ignores unmapped non-array non-stats events', function (t) {
+  const ocrGgml = createMinimalOcr()
+
+  const response = ocrGgml._job.start()
+  let outputCalled = false
+  response.onUpdate(() => { outputCalled = true })
+
+  ocrGgml._addonOutputCallback(null, 'CustomEvent', 'string data', null)
+
+  t.not(outputCalled, 'output should not be called for unmapped string data')
+  t.ok(ocrGgml._job.active, 'active response should still exist')
+})
+
+// =============================================
+// addonLogging.js coverage
+// =============================================
+
+test('addonLogging exports setLogger and releaseLogger as functions', function (t) {
+  const { addonLogging: logging } = require('../..')
+  t.is(typeof logging.setLogger, 'function')
+  t.is(typeof logging.releaseLogger, 'function')
+})
+
+test('addonLogging setLogger and releaseLogger execute without error', function (t) {
+  const { addonLogging: logging } = require('../..')
+  logging.setLogger(function () {})
+  t.pass('setLogger accepted a callback')
+  logging.releaseLogger()
+  t.pass('releaseLogger completed')
+})
+
+// =============================================
+// Optional performance params: defaultRotationAngles, contrastRetry
+// =============================================
+
+test('load() accepts defaultRotationAngles and contrastRetry', { timeout: TEST_TIMEOUT }, async function (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+  const imagePath = getImagePath('/test/images/basic_test.bmp')
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en'],
+      defaultRotationAngles: [90, 180, 270],
+      contrastRetry: true
+    }
+  })
+
+  await ocrGgml.load()
+  t.pass('Loaded with defaultRotationAngles + contrastRetry')
+
+  try {
+    const response = await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+
+    await response
+      .onUpdate(function (output) {
+        t.ok(Array.isArray(output), 'Output should be an array')
+      })
+      .onError(function (error) {
+        t.fail('Unexpected error: ' + JSON.stringify(error))
+      })
+      .await()
+
+    t.pass('Inference completed with extra params')
+  } finally {
+    await ocrGgml.unload()
+    await new Promise(function (resolve) { setTimeout(resolve, 1000) })
+  }
+})
+
+// =============================================
+// OcrGgmlInterface catch blocks via monkey-patching
+// (ocr-ggml.js: activate, runJob, destroy)
+// =============================================
+
+test('activate catch wraps error as FAILED_TO_ACTIVATE', { timeout: TEST_TIMEOUT }, async function (t) {
+  const ocrGgml = await loadOcr()
+  const addonRef = ocrGgml.addon
+
+  const original = binding.activate
+  binding.activate = function () { throw new Error('simulated activate failure') }
+
+  try {
+    await addonRef.activate()
+    t.fail('Should have thrown')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Error is QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.FAILED_TO_ACTIVATE)
+    t.ok(err.message.includes('simulated activate failure'))
+  } finally {
+    binding.activate = original
+    await ocrGgml.unload()
+    await new Promise(function (resolve) { setTimeout(resolve, 1000) })
+  }
+})
+
+test('runJob catch wraps error as FAILED_TO_RUN_JOB', { timeout: TEST_TIMEOUT }, async function (t) {
+  const ocrGgml = await loadOcr()
+  const addonRef = ocrGgml.addon
+
+  const original = binding.runJob
+  binding.runJob = function () { throw new Error('simulated runJob failure') }
+
+  try {
+    await addonRef.runJob({ type: 'image', input: {}, options: {} })
+    t.fail('Should have thrown')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Error is QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.FAILED_TO_RUN_JOB)
+    t.ok(err.message.includes('simulated runJob failure'))
+  } finally {
+    binding.runJob = original
+    await ocrGgml.unload()
+    await new Promise(function (resolve) { setTimeout(resolve, 1000) })
+  }
+})
+
+test('destroy catch wraps error as FAILED_TO_DESTROY', { timeout: TEST_TIMEOUT }, async function (t) {
+  const ocrGgml = await loadOcr()
+  const addonRef = ocrGgml.addon
+
+  const original = binding.destroyInstance
+  binding.destroyInstance = function () { throw new Error('simulated destroy failure') }
+
+  try {
+    await addonRef.destroy()
+    t.fail('Should have thrown')
+  } catch (err) {
+    t.ok(err instanceof QvacErrorAddonOcrGgml, 'Error is QvacErrorAddonOcrGgml')
+    t.is(err.code, ERR_CODES.FAILED_TO_DESTROY)
+    t.ok(err.message.includes('simulated destroy failure'))
+  } finally {
+    binding.destroyInstance = original
+    try { await addonRef.destroy() } catch (e) { /* real cleanup */ }
+    ocrGgml.addon = null
+    await new Promise(function (resolve) { setTimeout(resolve, 1000) })
+  }
+})
+
+// =============================================
+// OcrGgmlInterface.cancel and .unload delegation
+// (ocr-ggml.js)
+// =============================================
+
+test('cancel calls binding.cancel', { timeout: TEST_TIMEOUT }, async function (t) {
+  const ocrGgml = await loadOcr()
+  const addonRef = ocrGgml.addon
+
+  let cancelCalled = false
+  const original = binding.cancel
+  binding.cancel = function () { cancelCalled = true }
+
+  try {
+    await addonRef.cancel()
+    t.ok(cancelCalled, 'binding.cancel was called')
+  } finally {
+    binding.cancel = original
+    await ocrGgml.unload()
+    await new Promise(function (resolve) { setTimeout(resolve, 1000) })
+  }
+})
+
+test('OcrGgmlInterface.unload delegates to destroy', { timeout: TEST_TIMEOUT }, async function (t) {
+  const ocrGgml = await loadOcr()
+  const addonRef = ocrGgml.addon
+
+  let destroyCalled = false
+  const original = binding.destroyInstance
+  binding.destroyInstance = function (handle) {
+    destroyCalled = true
+    return original(handle)
+  }
+
+  try {
+    await addonRef.unload()
+    t.ok(destroyCalled, 'unload delegated to destroy')
+    t.is(addonRef._handle, null, 'Handle set to null after unload')
+  } finally {
+    binding.destroyInstance = original
+    ocrGgml.addon = null
+    await new Promise(function (resolve) { setTimeout(resolve, 1000) })
+  }
+})