@qvac/tts-ggml 0.9.0 → 0.9.2

package/README.md

@@ -119,8 +119,9 @@ npm install @qvac/tts-ggml
 Requires [Bare](https://github.com/holepunchto/bare) `>=1.19.0`.
 
 `@qvac/tts-ggml` is a meta package that ships the JavaScript wrapper only.
-The native prebuild for each host lives in a version-locked platform package
-selected at install time through `os`/`cpu` filtered `optionalDependencies`:
+The native prebuild for each desktop host lives in a version-locked platform
+package selected at install time through `os`/`cpu` filtered
+`optionalDependencies`:
 
 | Host | Package |
 | --- | --- |
@@ -129,12 +130,10 @@ selected at install time through `os`/`cpu` filtered `optionalDependencies`:
 | darwin-arm64 | `@qvac/tts-ggml-darwin-arm64` |
 | darwin-x64 | `@qvac/tts-ggml-darwin-x64` |
 | win32-x64 | `@qvac/tts-ggml-win32-x64` |
-| android-arm64 | `@qvac/tts-ggml-android-arm64` |
-| ios (device + simulators) | `@qvac/tts-ggml-ios` |
 
-Do not depend on platform packages directly. Supported installers are npm 7+,
-pnpm, bun, and Yarn Berry. Yarn v1 and `--omit=optional` installs skip the
-platform package and fail at require time with an error naming the missing
+Do not depend on desktop platform packages directly. Supported installers are
+npm 7+, pnpm, bun, and Yarn Berry. Yarn v1 and `--omit=optional` installs skip
+the platform package and fail at require time with an error naming the missing
 package; a locally built `prebuilds/` directory in the package root always
 takes precedence. Use `require('@qvac/tts-ggml').resolveBackendsDir()` to
 locate the directory holding the host's prebuilt binaries and dynamically
@@ -142,6 +141,25 @@ loaded ggml backends. Unsupported targets must
 [build from source](#build-from-source); installation does not automatically
 compile a local addon.
 
+Mobile targets are cross-built, so no install host ever matches their `os`,
+and `optionalDependencies` filtering can never select them. Mobile
+applications must declare the target's platform package as a direct
+dependency, pinned to the exact `@qvac/tts-ggml` version:
+
+| Target | Package |
+| --- | --- |
+| android-arm64 | `@qvac/tts-ggml-android-arm64` |
+| ios (device + simulators) | `@qvac/tts-ggml-ios` |
+
+```json
+{
+  "dependencies": {
+    "@qvac/tts-ggml": "x.y.z",
+    "@qvac/tts-ggml-android-arm64": "x.y.z"
+  }
+}
+```
+
 ## Model files
 
 Five engine families are wrapped (Chatterbox, Supertonic, Parler,

package/binding.js

@@ -1,18 +1,52 @@
 module.exports = loadAddon()
 
+// `require.addon()` reads the prebuild shipped inside this package. Since the
+// per-platform split (0.9.0) there is none, so the real binding almost always
+// comes from the `#host-addon` platform package. Runtimes have been seen to
+// answer `require.addon()` with this package's own JavaScript entry instead of
+// failing, which used to be returned verbatim: callers then got a module with
+// no `createInstance`, and the first symptom was an unrelated TypeError deep in
+// a model load. Anything that is not the native binding is treated as a miss.
 function loadAddon() {
+  let cause = null
+
   try {
-    return require.addon()
+    const addon = require.addon()
+    if (isNativeBinding(addon)) return addon
+    cause = new Error(
+      '@qvac/tts-ggml: require.addon() answered with a module that is not the native binding ' +
+        '(no createInstance function), so the prebuild in this package was treated as absent.'
+    )
   } catch (err) {
-    return loadPlatformPackageAddon(err)
+    cause = err
   }
+
+  return loadPlatformPackageAddon(cause)
 }
 
 function loadPlatformPackageAddon(cause) {
+  let addon
+
   try {
-    return require('#host-addon')
+    addon = require('#host-addon')
   } catch (err) {
     if (err.cause === undefined) err.cause = cause
     throw err
   }
+
+  if (!isNativeBinding(addon)) {
+    const err = new Error(
+      '@qvac/tts-ggml resolved #host-addon to a module that is not the native binding: ' +
+        'it has no createInstance function. Check that the platform package for this host ' +
+        'is installed and is not shadowed by another module of the same name.'
+    )
+    err.cause = cause
+    throw err
+  }
+
+  return addon
+}
+
+function isNativeBinding(addon) {
+  return addon !== null && typeof addon === 'object' && typeof addon.createInstance === 'function'
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/tts-ggml",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Text to Speech (TTS) addon for qvac (ggml backend, wrapping the chatterbox + supertonic + parler + cosyvoice3 + audio8 engines from tts-cpp)",
   "addon": true,
   "engines": {
@@ -79,10 +79,10 @@
     "example:parler-enhanced": "bare examples/parler-enhanced.js \"Hello from enhanced Parler.\"",
     "example:audio8": "bare examples/audio8-tts.js \"Audio eight speaks on-device.\"",
     "lint": "npm run lint:js && npm run lint:ts && npm run test:types",
-    "lint:js": "prettier --check \"test/**/*.js\" \"scripts/__tests__/package-contract.test.js\" \"binding.js\" \"addon-unavailable.js\" && lunte \"test/**/*.js\" \"scripts/__tests__/package-contract.test.js\" \"binding.js\" \"addon-unavailable.js\"",
+    "lint:js": "prettier --check \"test/**/*.js\" \"scripts/__tests__/package-contract.test.js\" \"scripts/__tests__/binding-loader.test.js\" \"binding.js\" \"addon-unavailable.js\" && lunte \"test/**/*.js\" \"scripts/__tests__/package-contract.test.js\" \"scripts/__tests__/binding-loader.test.js\" \"binding.js\" \"addon-unavailable.js\"",
     "lint:ts": "eslint \"src/**/*.ts\" --max-warnings=0",
     "lint:ts:fix": "eslint \"src/**/*.ts\" --fix",
-    "format": "prettier --write \"test/**/*.js\" \"scripts/__tests__/package-contract.test.js\" \"binding.js\" \"addon-unavailable.js\"",
+    "format": "prettier --write \"test/**/*.js\" \"scripts/__tests__/package-contract.test.js\" \"scripts/__tests__/binding-loader.test.js\" \"binding.js\" \"addon-unavailable.js\"",
     "test:unit": "npm run build:ts && brittle-bare test/unit/**/*.test.js && npm run test:node",
     "test:node": "node --test scripts/__tests__/*.test.js",
     "test": "npm run test:types && npm run test:unit && npm run test:integration",
@@ -209,12 +209,10 @@
   },
   "types": "index.d.ts",
   "optionalDependencies": {
-    "@qvac/tts-ggml-linux-x64": "0.9.0",
-    "@qvac/tts-ggml-linux-arm64": "0.9.0",
-    "@qvac/tts-ggml-darwin-arm64": "0.9.0",
-    "@qvac/tts-ggml-darwin-x64": "0.9.0",
-    "@qvac/tts-ggml-win32-x64": "0.9.0",
-    "@qvac/tts-ggml-android-arm64": "0.9.0",
-    "@qvac/tts-ggml-ios": "0.9.0"
+    "@qvac/tts-ggml-linux-x64": "0.9.2",
+    "@qvac/tts-ggml-linux-arm64": "0.9.2",
+    "@qvac/tts-ggml-darwin-arm64": "0.9.2",
+    "@qvac/tts-ggml-darwin-x64": "0.9.2",
+    "@qvac/tts-ggml-win32-x64": "0.9.2"
   }
 }