@pproenca/node-webcodecs 0.1.0 → 0.1.1-alpha.5

package/lib/types.ts

@@ -19,6 +19,34 @@ export type BufferSource = ArrayBuffer | ArrayBufferView;
 /** WebIDL: typedef double DOMHighResTimeStamp */
 export type DOMHighResTimeStamp = number;
 
+// =============================================================================
+// NODE.JS EXTENSIONS
+// =============================================================================
+
+/**
+ * ImageData interface for canvas integration.
+ * Matches the return type of canvas.getContext('2d').getImageData().
+ * Self-describing: contains width, height, and RGBA pixel data.
+ *
+ * Note: This is a Node.js extension to WebCodecs, providing equivalent
+ * functionality to CanvasImageSource for server-side canvas integration.
+ *
+ * @example
+ * ```typescript
+ * import { createCanvas } from 'canvas';
+ * const canvas = createCanvas(640, 480);
+ * const ctx = canvas.getContext('2d');
+ * // ... draw to canvas ...
+ * const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+ * const frame = new VideoFrame(imageData, { timestamp: 0 });
+ * ```
+ */
+export interface ImageDataLike {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8ClampedArray;
+}
+
 // =============================================================================
 // CODEC STATE
 // =============================================================================
@@ -54,6 +82,17 @@ export type HardwareAcceleration = 'no-preference' | 'prefer-hardware' | 'prefer
  */
 export type AlphaOption = 'keep' | 'discard';
 
+/**
+ * WebIDL:
+ * enum PremultiplyAlpha { "none", "premultiply", "default" };
+ *
+ * Per W3C WebCodecs spec:
+ * - "none": Do not premultiply alpha
+ * - "premultiply": Premultiply RGB values by alpha
+ * - "default": Use default behavior (typically none)
+ */
+export type PremultiplyAlpha = 'none' | 'premultiply' | 'default';
+
 // =============================================================================
 // LATENCY MODE
 // =============================================================================
@@ -788,6 +827,7 @@ export type ImageBufferSource = AllowSharedBufferSource | ReadableStream<Uint8Ar
  *   required DOMString type;
  *   required ImageBufferSource data;
  *   ColorSpaceConversion colorSpaceConversion = "default";
+ *   PremultiplyAlpha premultiplyAlpha = "default";
  *   [EnforceRange] unsigned long desiredWidth;
  *   [EnforceRange] unsigned long desiredHeight;
  *   boolean preferAnimation;
@@ -798,6 +838,7 @@ export interface ImageDecoderInit {
   type: string;
   data: ImageBufferSource;
   colorSpaceConversion?: ColorSpaceConversion;
+  premultiplyAlpha?: PremultiplyAlpha;
   desiredWidth?: number;
   desiredHeight?: number;
   preferAnimation?: boolean;
@@ -1075,10 +1116,20 @@ export interface ImageDecoderConstructor {
  * WebIDL:
  *   constructor(CanvasImageSource image, optional VideoFrameInit init = {});
  *   constructor(AllowSharedBufferSource data, VideoFrameBufferInit init);
+ *
+ * Note: CanvasImageSource (DOM-based) not available in Node.js.
+ * Node.js alternatives:
+ *   - ImageDataLike: Self-describing RGBA buffer from canvas.getImageData()
+ *   - VideoFrame: Clone/crop existing frames
+ *   - AllowSharedBufferSource: Raw pixel data with explicit format/dimensions
  */
 export interface VideoFrameConstructor {
-  // Note: CanvasImageSource constructor not supported (Node.js has no DOM)
+  /** Construct from ImageData (canvas.getImageData() compatible) */
+  new (imageData: ImageDataLike, init?: VideoFrameInit): VideoFrame;
+  /** Construct from raw pixel buffer with explicit format */
   new (data: AllowSharedBufferSource, init: VideoFrameBufferInit): VideoFrame;
+  /** Construct from existing VideoFrame (clone/crop) */
+  new (source: VideoFrame, init?: VideoFrameInit): VideoFrame;
 }
 
 /**

package/lib/video-decoder.ts

@@ -17,6 +17,9 @@ import { VideoFrame } from './video-frame';
 // Load native addon with type assertion
 const native = binding as NativeModule;
 
+// Default backpressure threshold for limiting in-flight chunks
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
+
 export class VideoDecoder extends CodecBase {
   private _native: NativeVideoDecoder;
   private _controlQueue: ControlMessageQueue;
@@ -25,6 +28,9 @@ export class VideoDecoder extends CodecBase {
   private _errorCallback: (error: DOMException) => void;
   private _resourceId: symbol;
 
+  // Backpressure support
+  private _maxQueueDepth: number = DEFAULT_MAX_QUEUE_DEPTH;
+
   constructor(init: VideoDecoderInit) {
     super();
     // W3C spec: output and error callbacks are required
@@ -38,7 +44,6 @@ export class VideoDecoder extends CodecBase {
     this._resourceId = ResourceManager.getInstance().register(this);
 
     const outputCallback: VideoDecoderOutputCallback = (nativeFrame) => {
-      // Decrement queue size when output received
       this._decodeQueueSize = Math.max(0, this._decodeQueueSize - 1);
 
       // Wrap the native frame as a VideoFrame
@@ -71,11 +76,78 @@ export class VideoDecoder extends CodecBase {
     return this._native.codecSaturated;
   }
 
+  /**
+   * Returns a Promise that resolves when the decoder has capacity for more chunks.
+   * Use this to implement backpressure in high-throughput decoding pipelines.
+   *
+   * When the internal queue is full (decodeQueueSize >= maxQueueDepth), calling
+   * `await decoder.ready` will pause until capacity is available.
+   *
+   * @example
+   * for (const chunk of chunks) {
+   *   await decoder.ready;  // Wait for capacity
+   *   decoder.decode(chunk);
+   * }
+   */
+  get ready(): Promise<void> {
+    // If we have capacity, resolve immediately
+    if (this._decodeQueueSize < this._maxQueueDepth) {
+      return Promise.resolve();
+    }
+
+    // Otherwise, poll until capacity is available.
+    // We use setTimeout(1ms) polling to allow TSFN output callbacks to execute.
+    // setTimeout ensures we yield through the full event loop cycle, including
+    // the I/O phase where TSFN callbacks are delivered.
+    return new Promise<void>((resolve) => {
+      const checkCapacity = () => {
+        if (this._decodeQueueSize < this._maxQueueDepth) {
+          resolve();
+        } else {
+          // Yield full event loop cycle to allow output callbacks to run
+          setTimeout(checkCapacity, 1);
+        }
+      };
+      // Initial yield to allow any pending callbacks to run
+      setTimeout(checkCapacity, 1);
+    });
+  }
+
+  /**
+   * The maximum queue depth before backpressure is applied.
+   * Default is 16. Adjust based on memory constraints and frame size.
+   */
+  get maxQueueDepth(): number {
+    return this._maxQueueDepth;
+  }
+
+  set maxQueueDepth(value: number) {
+    if (value < 1) {
+      throw new RangeError('maxQueueDepth must be at least 1');
+    }
+    this._maxQueueDepth = value;
+  }
+
   configure(config: VideoDecoderConfig): void {
     // W3C spec: throw if closed
     if (this.state === 'closed') {
       throw new DOMException('Decoder is closed', 'InvalidStateError');
     }
+
+    // Validate rotation (node-webcodecs extension)
+    if ('rotation' in config && config.rotation !== undefined) {
+      if (![0, 90, 180, 270].includes(config.rotation)) {
+        throw new TypeError(`rotation must be 0, 90, 180, or 270, got ${config.rotation}`);
+      }
+    }
+
+    // Validate flip (node-webcodecs extension)
+    if ('flip' in config && config.flip !== undefined) {
+      if (typeof config.flip !== 'boolean') {
+        throw new TypeError('flip must be a boolean');
+      }
+    }
+
     this._needsKeyFrame = true;
     // Configure synchronously to set state immediately per W3C spec
     this._native.configure(config);
@@ -111,7 +183,17 @@ export class VideoDecoder extends CodecBase {
       return Promise.reject(new DOMException('Decoder is closed', 'InvalidStateError'));
     }
     await this._controlQueue.flush();
-    return this._native.flush();
+
+    // Flush the native decoder (waits for worker queue to drain)
+    this._native.flush();
+
+    // Poll for pending TSFN callbacks to complete.
+    // This allows the event loop to run (delivering callbacks) while we wait.
+    // Using setTimeout(1ms) instead of setImmediate to ensure other event loop
+    // phases (timers, I/O) can run, preventing event loop starvation.
+    while (this._native.pendingFrames > 0) {
+      await new Promise((resolve) => setTimeout(resolve, 1)); // 1ms poll
+    }
   }
 
   reset(): void {

package/lib/video-encoder.ts

@@ -17,12 +17,18 @@ import type { VideoFrame } from './video-frame';
 // Load native addon with type assertion
 const native = binding as NativeModule;
 
+// Default backpressure threshold for limiting in-flight frames
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
+
 export class VideoEncoder extends CodecBase {
   private _native: NativeVideoEncoder;
   private _controlQueue: ControlMessageQueue;
   private _encodeQueueSize: number = 0;
   private _resourceId: symbol;
 
+  // Backpressure support
+  private _maxQueueDepth: number = DEFAULT_MAX_QUEUE_DEPTH;
+
   constructor(init: VideoEncoderInit) {
     super();
     // W3C spec: output and error callbacks are required
@@ -35,19 +41,32 @@ export class VideoEncoder extends CodecBase {
     this._resourceId = ResourceManager.getInstance().register(this);
 
     const outputCallback: VideoEncoderOutputCallback = (chunk, metadata) => {
-      // Decrement queue size when output received
       this._encodeQueueSize = Math.max(0, this._encodeQueueSize - 1);
 
-      const wrappedChunk = new EncodedVideoChunk({
-        type: chunk.type as 'key' | 'delta',
-        timestamp: chunk.timestamp,
-        duration: chunk.duration ?? undefined,
-        data: chunk.data,
-      });
+      // The native layer now returns an EncodedVideoChunk directly (not a plain object).
+      // Check if it's already a native chunk (has close method) vs plain object (has data buffer).
+      // Native chunks have close() but no 'data' property; plain objects have 'data' buffer.
+      let wrappedChunk: EncodedVideoChunk;
+      if ('data' in chunk && chunk.data instanceof Buffer) {
+        // Legacy path: plain object from sync encoder - wrap it
+        wrappedChunk = new EncodedVideoChunk({
+          type: chunk.type as 'key' | 'delta',
+          timestamp: chunk.timestamp,
+          duration: chunk.duration ?? undefined,
+          data: chunk.data,
+        });
+      } else {
+        // New path: already a native EncodedVideoChunk from async encoder
+        // Wrap without copying data
+        wrappedChunk = EncodedVideoChunk._fromNative(
+          chunk as unknown as import('./native-types').NativeEncodedVideoChunk,
+        );
+      }
       init.output(wrappedChunk, metadata);
 
       // Fire ondequeue after output
       this._triggerDequeue();
+
     };
 
     this._native = new native.VideoEncoder({
@@ -68,6 +87,59 @@ export class VideoEncoder extends CodecBase {
     return this._native.codecSaturated;
   }
 
+  /**
+   * Returns a Promise that resolves when the encoder has capacity for more frames.
+   * Use this to implement backpressure in high-throughput encoding pipelines.
+   *
+   * When the internal queue is full (encodeQueueSize >= maxQueueDepth), calling
+   * `await encoder.ready` will pause until capacity is available.
+   *
+   * @example
+   * for (const frame of frames) {
+   *   await encoder.ready;  // Wait for capacity
+   *   encoder.encode(frame);
+   *   frame.close();
+   * }
+   */
+  get ready(): Promise<void> {
+    // If we have capacity, resolve immediately
+    if (this._encodeQueueSize < this._maxQueueDepth) {
+      return Promise.resolve();
+    }
+
+    // Otherwise, poll until capacity is available.
+    // We use setTimeout(1ms) polling to allow TSFN output callbacks to execute.
+    // setTimeout ensures we yield through the full event loop cycle, including
+    // the I/O phase where TSFN callbacks are delivered.
+    return new Promise<void>((resolve) => {
+      const checkCapacity = () => {
+        if (this._encodeQueueSize < this._maxQueueDepth) {
+          resolve();
+        } else {
+          // Yield full event loop cycle to allow output callbacks to run
+          setTimeout(checkCapacity, 1);
+        }
+      };
+      // Initial yield to allow any pending callbacks to run
+      setTimeout(checkCapacity, 1);
+    });
+  }
+
+  /**
+   * The maximum queue depth before backpressure is applied.
+   * Default is 16. Adjust based on memory constraints and frame size.
+   */
+  get maxQueueDepth(): number {
+    return this._maxQueueDepth;
+  }
+
+  set maxQueueDepth(value: number) {
+    if (value < 1) {
+      throw new RangeError('maxQueueDepth must be at least 1');
+    }
+    this._maxQueueDepth = value;
+  }
+
   configure(config: VideoEncoderConfig): void {
     // W3C spec: throw if closed
     if (this.state === 'closed') {
@@ -84,6 +156,10 @@ export class VideoEncoder extends CodecBase {
   }
 
   encode(frame: VideoFrame, options?: { keyFrame?: boolean }): void {
+    // W3C spec: throw if not configured
+    if (this.state !== 'configured') {
+      throw new DOMException(`Encoder is ${this.state}`, 'InvalidStateError');
+    }
     ResourceManager.getInstance().recordActivity(this._resourceId);
     this._encodeQueueSize++;
     // Call native encode directly - frame must be valid at call time
@@ -105,12 +181,18 @@ export class VideoEncoder extends CodecBase {
 
     // Poll for pending TSFN callbacks to complete.
     // This allows the event loop to run (delivering callbacks) while we wait.
+    // Using setTimeout(1ms) instead of setImmediate to ensure other event loop
+    // phases (timers, I/O) can run, preventing event loop starvation.
     while (this._native.pendingChunks > 0) {
-      await new Promise((resolve) => setImmediate(resolve));
+      await new Promise((resolve) => setTimeout(resolve, 1)); // 1ms poll
     }
   }
 
   reset(): void {
+    // W3C spec: throw if closed
+    if (this.state === 'closed') {
+      throw new DOMException('Encoder is closed', 'InvalidStateError');
+    }
     this._controlQueue.clear();
     this._encodeQueueSize = 0;
     this._native.reset();

package/lib/video-frame.ts

@@ -5,6 +5,7 @@
  */
 
 import { binding } from './binding';
+import { isImageData, type ImageDataLike } from './is';
 import type { NativeModule, NativeVideoFrame } from './native-types';
 import { detachArrayBuffers } from './transfer';
 import type {
@@ -62,21 +63,65 @@ export class VideoFrame {
   };
 
   /**
-   * Constructs a VideoFrame from raw data or from an existing VideoFrame.
+   * Constructs a VideoFrame from raw data, ImageData, or from an existing VideoFrame.
    *
    * Per W3C WebCodecs spec, VideoFrame can be constructed from:
-   * 1. Raw buffer data with VideoFrameBufferInit
-   * 2. An existing VideoFrame with optional VideoFrameInit overrides
+   * 1. ImageData - self-describing RGBA buffer (Node.js alternative to CanvasImageSource)
+   * 2. Raw buffer data with VideoFrameBufferInit
+   * 3. An existing VideoFrame with optional VideoFrameInit overrides
    */
+  constructor(imageData: ImageDataLike, init?: VideoFrameInit);
   constructor(data: Buffer | Uint8Array | ArrayBuffer, init: VideoFrameBufferInit);
   constructor(source: VideoFrame, init?: VideoFrameInit);
   constructor(
-    dataOrSource: Buffer | Uint8Array | ArrayBuffer | VideoFrame,
+    dataOrSourceOrImageData: Buffer | Uint8Array | ArrayBuffer | VideoFrame | ImageDataLike,
     init?: VideoFrameBufferInit | VideoFrameInit,
   ) {
+    // Check if constructing from ImageData (self-describing RGBA)
+    // ImageData is canvas.getContext('2d').getImageData() compatible
+    if (isImageData(dataOrSourceOrImageData)) {
+      const imageData = dataOrSourceOrImageData;
+      const frameInit = init as VideoFrameInit | undefined;
+
+      // Validate data size matches dimensions (width * height * 4 for RGBA)
+      const expectedSize = imageData.width * imageData.height * 4;
+      if (imageData.data.length !== expectedSize) {
+        throw new TypeError(
+          `ImageData.data length (${imageData.data.length}) does not match ` +
+            `expected size (${expectedSize}) for ${imageData.width}x${imageData.height} RGBA`,
+        );
+      }
+
+      // Convert Uint8ClampedArray to Buffer for native binding
+      const dataBuffer = Buffer.from(
+        imageData.data.buffer,
+        imageData.data.byteOffset,
+        imageData.data.byteLength,
+      );
+
+      // Build VideoFrameBufferInit from ImageData dimensions
+      // ImageData is always RGBA format from canvas
+      const bufferInit: VideoFrameBufferInit = {
+        format: 'RGBA',
+        codedWidth: imageData.width,
+        codedHeight: imageData.height,
+        timestamp: frameInit?.timestamp ?? 0,
+        duration: frameInit?.duration,
+        visibleRect: frameInit?.visibleRect,
+        displayWidth: frameInit?.displayWidth ?? imageData.width,
+        displayHeight: frameInit?.displayHeight ?? imageData.height,
+        metadata: frameInit?.metadata,
+      };
+
+      this._native = new native.VideoFrame(dataBuffer, bufferInit);
+      this._metadata = bufferInit.metadata ?? {};
+      this._closed = false;
+      return;
+    }
+
     // Check if constructing from existing VideoFrame
-    if (dataOrSource instanceof VideoFrame) {
-      const source = dataOrSource;
+    if (dataOrSourceOrImageData instanceof VideoFrame) {
+      const source = dataOrSourceOrImageData;
       const frameInit = init as VideoFrameInit | undefined;
 
       // W3C spec: throw InvalidStateError if source frame is closed (detached)
@@ -125,7 +170,7 @@ export class VideoFrame {
     }
 
     // Original buffer-based construction
-    const data = dataOrSource;
+    const data = dataOrSourceOrImageData;
     const bufferInit = init as VideoFrameBufferInit;
 
     // Convert to Buffer if needed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pproenca/node-webcodecs",
   "description": "WebCodecs API implementation for Node.js using FFmpeg",
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.5",
   "author": "Pedro Proenca",
   "homepage": "https://github.com/pproenca/node-webcodecs",
   "repository": {
@@ -12,29 +12,48 @@
     "url": "https://github.com/pproenca/node-webcodecs/issues"
   },
   "scripts": {
-    "build": "npm run build:native && npm run build:ts",
-    "build:ts": "tsc",
+    "build": "node-gyp rebuild && tsc",
     "build:native": "node-gyp rebuild",
-    "build:native:debug": "node-gyp rebuild --debug",
-    "install": "node install/check.js || npm run build",
+    "build:ts": "tsc",
+    "build:debug": "node-gyp rebuild --debug && tsc",
+    "rebuild": "npm run clean && npm run build",
+    "install": "node-gyp-build",
     "clean": "rm -rf src/build/ .nyc_output/ coverage/ test/fixtures/output.*",
-    "test": "npm run lint && npm run test-unit",
-    "lint": "npm run lint-cpp && npm run lint-js && npm run lint-types",
-    "lint-cpp": "cpplint --quiet src/*.h src/*.cc",
-    "lint-js": "biome lint",
-    "lint-types": "tsd",
-    "test-unit": "vitest run --config test/vitest.config.ts",
-    "package-from-local-build": "node npm/from-local-build.js",
-    "package-release-notes": "node npm/release-notes.js"
+    "check": "npm run lint && npm test",
+    "test": "npm run test:fast && npm run test:guardrails",
+    "test:fast": "tsx --test --test-concurrency=1 --import ./test/setup.ts --test-timeout=30000 test/golden/*.test.ts test/unit/*.test.ts",
+    "test:golden": "tsx --test --test-concurrency=1 --import ./test/setup.ts --test-timeout=30000 test/golden/*.test.ts",
+    "test:unit": "tsx --test --test-concurrency=1 --import ./test/setup.ts --test-timeout=30000 test/unit/*.test.ts",
+    "test:stress": "tsx --test --test-concurrency=1 --import ./test/setup.ts --test-timeout=60000 test/stress/*.test.ts",
+    "test:contracts": "node test/contracts/video_encoder/state_machine.js && node test/contracts/audio_encoder/state_machine.js && node test/contracts/video_decoder/state_machine.js && node test/contracts/audio_decoder/state_machine.js",
+    "test:guardrails": "node test/guardrails/fuzzer.js && node test/guardrails/event_loop_lag.js",
+    "test:coverage": "c8 --check-coverage --lines 70 --branches 60 --functions 70 --statements 70 --include lib/**/*.ts --exclude lib/**/*.d.ts --exclude lib/types.ts npm run test:fast",
+    "lint": "npm run lint:cpp && npm run lint:ts && npm run lint:types && npm run lint:md",
+    "lint:cpp": "cpplint --quiet src/*.h src/*.cc",
+    "lint:ts": "biome lint",
+    "lint:types": "tsd",
+    "lint:md": "prettier --check \"**/*.md\"",
+    "format": "npm run format:md",
+    "format:md": "prettier --write \"**/*.md\"",
+    "version:bump": "node scripts/bump-version.js",
+    "create-platform-packages": "node scripts/create-platform-packages.mjs"
   },
   "type": "commonjs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
   "files": [
-    "install",
     "lib",
     "dist",
-    "src/*.{cc,h,gyp}"
+    "src/*.{cc,h,gyp}",
+    "binding.gyp"
   ],
   "keywords": [
     "webcodecs",
@@ -46,35 +65,33 @@
   "tsd": {
     "directory": "test/types"
   },
+  "optionalDependencies": {
+    "@pproenca/node-webcodecs-darwin-arm64": "0.1.1-alpha.5",
+    "@pproenca/node-webcodecs-darwin-x64": "0.1.1-alpha.5",
+    "@pproenca/node-webcodecs-linux-x64": "0.1.1-alpha.5"
+  },
   "dependencies": {
-    "detect-libc": "^2.0.3",
     "node-gyp-build": "^4.8.0"
   },
-  "optionalDependencies": {
-    "@pproenca/node-webcodecs-darwin-arm64": "0.1.0",
-    "@pproenca/node-webcodecs-darwin-x64": "0.1.0",
-    "@pproenca/node-webcodecs-linux-x64": "0.1.0",
-    "@pproenca/node-webcodecs-linuxmusl-x64": "0.1.0",
-    "@pproenca/node-webcodecs-win32-x64": "0.1.0"
-  },
   "devDependencies": {
     "@biomejs/biome": "^2.3.10",
     "@cpplint/cli": "^0.1.0",
-    "@types/node": "*",
-    "c8": "^10.1.2",
+    "@types/node": "^25.0.3",
+    "c8": "^10.1.3",
     "express": "^5.2.1",
-    "mediabunny": "^1.25.4",
-    "node-addon-api": "^8.0.0",
-    "node-gyp": "^10.0.0",
+    "mediabunny": "^1.27.3",
+    "node-addon-api": "^8.5.0",
+    "node-gyp": "^12.1.0",
+    "prebuildify": "^6.0.1",
+    "prettier": "^3.7.4",
     "tsd": "^0.33.0",
-    "tsx": "^4.20.6",
+    "tsx": "^4.21.0",
     "typedoc": "^0.28.15",
-    "typescript": "^5.6.3",
-    "vitest": "^4.0.15"
+    "typescript": "^5.9.3"
   },
   "license": "MIT",
   "engines": {
-    "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+    "node": "^20.17.0 || ^22.9.0 || >=24"
   },
   "publishConfig": {
     "access": "public",

package/src/addon.cc

@@ -41,6 +41,45 @@ void ClearFFmpegWarningsJS(const Napi::CallbackInfo& info) {
   webcodecs::ClearFFmpegWarnings();
 }
 
+// Counter accessor functions (following sharp pattern for observability)
+Napi::Value GetCounterQueueJS(const Napi::CallbackInfo& info) {
+  return Napi::Number::New(info.Env(), webcodecs::counterQueue.load());
+}
+
+Napi::Value GetCounterProcessJS(const Napi::CallbackInfo& info) {
+  return Napi::Number::New(info.Env(), webcodecs::counterProcess.load());
+}
+
+Napi::Value GetCounterFramesJS(const Napi::CallbackInfo& info) {
+  return Napi::Number::New(info.Env(), webcodecs::counterFrames.load());
+}
+
+Napi::Value GetCountersJS(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  Napi::Object counters = Napi::Object::New(env);
+
+  // New per-class counters
+  counters.Set("videoFrames",
+               static_cast<double>(webcodecs::counterVideoFrames.load()));
+  counters.Set("audioData",
+               static_cast<double>(webcodecs::counterAudioData.load()));
+  counters.Set("videoEncoders",
+               static_cast<double>(webcodecs::counterVideoEncoders.load()));
+  counters.Set("videoDecoders",
+               static_cast<double>(webcodecs::counterVideoDecoders.load()));
+  counters.Set("audioEncoders",
+               static_cast<double>(webcodecs::counterAudioEncoders.load()));
+  counters.Set("audioDecoders",
+               static_cast<double>(webcodecs::counterAudioDecoders.load()));
+
+  // Legacy counters (for backwards compatibility)
+  counters.Set("queue", webcodecs::counterQueue.load());
+  counters.Set("process", webcodecs::counterProcess.load());
+  counters.Set("frames", webcodecs::counterFrames.load());
+
+  return counters;
+}
+
 // Test helper for AttrAsEnum template
 Napi::Value TestAttrAsEnum(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
@@ -54,11 +93,22 @@ Napi::Value TestAttrAsEnum(const Napi::CallbackInfo& info) {
   return Napi::String::New(env, webcodecs::ColorPrimariesToString(primaries));
 }
 
+// Cleanup hook called when the Node.js environment is being torn down.
+// This prevents the static destruction order fiasco where FFmpeg's log
+// callback might access destroyed static objects during process exit.
+static void CleanupCallback(void* arg) {
+  webcodecs::ShutdownFFmpegLogging();
+}
+
 Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
   // Thread-safe FFmpeg initialization
   webcodecs::InitFFmpeg();
   webcodecs::InitFFmpegLogging();
 
+  // Register cleanup hook to disable FFmpeg logging before static destructors.
+  // This fixes crashes on macOS x64 where FFmpeg logs during process exit.
+  napi_add_env_cleanup_hook(env, CleanupCallback, nullptr);
+
   InitVideoEncoder(env, exports);
   InitVideoDecoder(env, exports);
   InitVideoFrame(env, exports);
@@ -82,6 +132,13 @@ Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
   exports.Set("clearFFmpegWarnings",
               Napi::Function::New(env, ClearFFmpegWarningsJS));
 
+  // Export global counter functions (following sharp pattern for observability)
+  exports.Set("getCounterQueue", Napi::Function::New(env, GetCounterQueueJS));
+  exports.Set("getCounterProcess",
+              Napi::Function::New(env, GetCounterProcessJS));
+  exports.Set("getCounterFrames", Napi::Function::New(env, GetCounterFramesJS));
+  exports.Set("getCounters", Napi::Function::New(env, GetCountersJS));
+
   // Export test helpers
   exports.Set("testAttrAsEnum", Napi::Function::New(env, TestAttrAsEnum));