fix(js): extract framework archives during npm install

.github/workflows/main.yml

@@ -225,7 +225,7 @@ jobs:
       run: npm install
 
     - name: Run Node.js tests
-      run: npx jest tests/
+      run: npx jest tests/rtms.test.ts
 
   # Test Node.js SDK on macOS using pre-built prebuilds
   test-nodejs-macos:
@@ -252,7 +252,34 @@ jobs:
       run: npm install
 
     - name: Run Node.js tests
-      run: npx jest tests/
+      run: npx jest tests/rtms.test.ts
+
+  # Integration test: npm pack → install → load (validates end-user install flow)
+  test-nodejs-integration-macos:
+    name: Test Node.js Install Flow (macOS)
+    runs-on: macos-latest
+    needs: [build-nodejs-macos]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js 24.x
+      uses: actions/setup-node@v4
+      with:
+        node-version: '24.x'
+
+    - name: Download prebuilds
+      uses: actions/download-artifact@v4
+      with:
+        name: prebuilds-darwin
+        path: prebuilds/
+
+    - name: Install dependencies
+      run: npm install
+
+    - name: Run integration test (npm pack → install → load)
+      run: npx jest tests/pack-install.test.js --testTimeout=120000
 
   # Test Python SDK on Linux using pre-built wheels
   test-python-linux:
@@ -350,7 +377,7 @@ jobs:
   check-version-change:
     name: Check for Version Changes
     runs-on: ubuntu-latest
-    needs: [test-nodejs-linux, test-nodejs-macos, test-python-linux, test-python-macos]
+    needs: [test-nodejs-linux, test-nodejs-macos, test-nodejs-integration-macos, test-python-linux, test-python-macos]
     if: |
       success() &&
       github.event_name == 'push' &&

.gitignore

@@ -46,6 +46,7 @@ scripts/**/*
 !src/rtms/*.pyi
 
 !tests/**.py
+!tests/**.js
 
 # MacOS
 .DS_Store

Taskfile.yml

@@ -215,7 +215,13 @@ tasks:
     desc: "Run Node.js tests (local)"
     deps: [build:js]
     cmds:
-      - npx jest tests/
+      - npx jest tests/rtms.test.ts
+
+  test:js:integration:
+    desc: "Run npm pack → install → load integration test"
+    deps: [build:js]
+    cmds:
+      - npx jest tests/pack-install.test.js --testTimeout=120000
 
   test:js:linux:
     desc: "Run Node.js tests in Linux Docker"

scripts/install.js

@@ -11,9 +11,10 @@
  */
 
 import { execSync } from 'child_process';
-import { existsSync } from 'fs';
+import { existsSync, readdirSync, unlinkSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import * as tar from 'tar';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -38,6 +39,47 @@ function warning(message) {
   console.log(`${colors.yellow}[RTMS Install]${colors.reset} ${message}`);
 }
 
+/**
+ * Extract macOS framework archives (.framework.tar.gz) after prebuild-install
+ *
+ * The prebuilt binaries include macOS frameworks as tar.gz archives to reduce size.
+ * These must be extracted for the native module to load correctly.
+ */
+function extractFrameworks(buildDir) {
+  if (process.platform !== 'darwin') {
+    // Frameworks only exist on macOS
+    return;
+  }
+
+  if (!existsSync(buildDir)) {
+    return;
+  }
+
+  const files = readdirSync(buildDir);
+  const frameworkArchives = files.filter(f => f.endsWith('.framework.tar.gz'));
+
+  if (frameworkArchives.length === 0) {
+    return;
+  }
+
+  log(`Extracting ${frameworkArchives.length} framework archive(s)...`);
+
+  for (const archive of frameworkArchives) {
+    const archivePath = join(buildDir, archive);
+    try {
+      tar.extract({
+        file: archivePath,
+        cwd: buildDir,
+        sync: true
+      });
+      // Remove the archive after extraction to save space
+      unlinkSync(archivePath);
+    } catch (err) {
+      warning(`Failed to extract ${archive}: ${err.message}`);
+    }
+  }
+}
+
 /**
  * Try to install prebuilt binary
  */
@@ -51,6 +93,10 @@ function installPrebuild() {
       env: process.env
     });
 
+    // Extract framework archives on macOS
+    const buildDir = join(__dirname, '..', 'build', 'Release');
+    extractFrameworks(buildDir);
+
     success('Prebuilt binary installed successfully!');
     return true;
   } catch (err) {