Plugin proxy is unintentionally Thenable: get-trap default returns function wrapper for 'then' / 'catch' / 'finally'

[playopsstudio]

Plugin proxy is unintentionally Thenable: get-trap default returns function wrapper for 'then' / 'catch' / 'finally'

Labels (suggested): bug, core, needs review

---

Summary

The plugin proxy created by registerPlugin() in core/src/runtime.ts:162-181 is unintentionally a JavaScript Thenable. Its get trap returns createPluginMethodWrapper(prop) for any property name not in the switch — including then, catch, and finally. Per ECMAScript Promise spec, any object with a callable .then is treated as a Thenable, causing surprising behavior when a plugin proxy passes through Promise resolution.

Mechanism

core/src/runtime.ts:165-178 (verified against main branch):

get(_, prop) {
  switch (prop) {
    // https://github.com/facebook/react/issues/20030
    case '$$typeof':
      return undefined;
    case 'toJSON':
      return () => ({});
    case 'addListener':
      return pluginHeader ? addListenerNative : addListener;
    case 'removeListener':
      return removeListener;
    default:
      return createPluginMethodWrapper(prop);
  }
},

When code holds a plugin proxy as a Promise resolution value, the JS engine's Thenable check fires:

1. Consumer code: const pluginPromise = import("some-capacitor-plugin").then((module) => module.SomePlugin); — common dynamic-import pattern for lazy plugin loading
2. The .then((module) => module.SomePlugin) callback returns the plugin proxy
3. Promise resolution machinery checks: is this returned value a Thenable? Reads .then on the proxy
4. Proxy get-trap returns createPluginMethodWrapper("then") — a function — JS engine treats proxy as Thenable
5. Promise resolution invokes proxy.then(resolve, reject) to chain
6. The wrapper dispatches cap.nativePromise(pluginName, "then", resolve) to the native bridge
7. No native plugin has @PluginMethod for then → bridge rejects with "PluginName.then() is not implemented on android" (or platform-equivalent)
8. The outer Promise.resolve(proxy) may hang (resolve/reject never invoked by the wrapper) AND/OR the inner cap.nativePromise rejection bubbles to window.unhandledrejection

The // https://github.com/facebook/react/issues/20030 comment at line 167 already acknowledges that proxies-passed-into-framework-machinery need explicit short-circuits (React's $$typeof check). The same issue applies to Promise machinery's .then/.catch/.finally checks — these need to return undefined for the same architectural reason.

Affected versions (empirically verified)

• @capacitor/core@8.3.1 (confirmed via dist/index.js:156-172)
• @capacitor/core@9.0.0-alpha.2 (confirmed via dist/index.js:159-167 — same proxy shape)
• main branch as of fetch (confirmed via core/src/runtime.ts:165-178)

Bug appears unchanged from at least 8.x through 9.0.0-alpha; likely present in 7.x and earlier.

Real-world failure surfaces

In a private game-runtime codebase using Capacitor 8.3.1 + multiple community plugins, we hit three production-surface symptoms of this bug, all sharing the same root cause:

1. await adMob.prepareForAds() race-throw: AdMob plugin proxy used via dynamic-import-then pattern; sometimes the await sees "AdMob.then() is not implemented on android" rejection before the actual prepareForAds() invocation. Timing-dependent due to cap.nativePromise dispatch race.
2. await iap.initialize() hang: IAP plugin proxy (different community plugin); same dynamic-import-then pattern; the Promise.resolve(proxy) chain calls proxy.then(resolve, reject) which never resolves the outer promise → hangs forever.
3. await createMonetizationBridge(...) hang: an async factory function whose internal addListener calls on the IAP proxy trigger the same bug at a different call surface.

We shipped a consumer-side workaround pattern (container-wrap):

// Before (buggy):
let pluginPromise: Promise<PluginType> | undefined;
const loadPlugin = (): Promise<PluginType> => {
  pluginPromise ??= import("some-plugin").then((m) => m.Plugin);
  return pluginPromise;
};

// After (workaround; defeats the Thenable check):
let pluginPromise: Promise<{ plugin: PluginType }> | undefined;
const loadPlugin = (): Promise<{ plugin: PluginType }> => {
  pluginPromise ??= import("some-plugin").then((m) => ({ plugin: m.Plugin }));
  return pluginPromise;
};
// Consumer:
const { plugin } = await loadPlugin();
await plugin.someMethod();

The container-wrap works because plain objects without a .then property are not Thenable. But this is fragile (every consumer-side dynamic-import must remember to wrap; a single oversight reintroduces the bug class).

Proposed fix

Add then, catch, and finally to the get-trap switch returning undefined:

get(_, prop) {
  switch (prop) {
    // https://github.com/facebook/react/issues/20030
    case '$$typeof':
      return undefined;
    case 'toJSON':
      return () => ({});
    case 'addListener':
      return pluginHeader ? addListenerNative : addListener;
    case 'removeListener':
      return removeListener;
    // Promise-machinery short-circuit. See #<issue-number> for failure modes.
    case 'then':
    case 'catch':
    case 'finally':
      return undefined;
    default:
      return createPluginMethodWrapper(prop);
  }
},

Matches the architectural precedent of $$typeof (React framework-machinery short-circuit). Zero runtime behavior change for any code that doesn't accidentally feed the proxy through Promise resolution; eliminates the latent footgun for code that does.

[ionitron-bot]

This issue needs more information before it can be addressed. In particular, the reporter needs to provide a minimal sample app that demonstrates the issue. If no sample app is provided within 7 days, the issue will be closed.
Please see the Contributing Guide for how to create a Sample App.
Thanks! Ionitron 💙

[playopsstudio]

capacitor#8472-comment.md

Minimal sample app reproducing the bug:
https://github.com/PlayOps-Studio-Org/capacitor-thenable-repro-issue-8472

The repo runs in pure Node against @capacitor/core@8.3.4 (no Android Studio / Xcode required to observe the bug surfaces):

npm install
node index.mjs
The script demonstrates three observable surfaces of the bug + the workaround that sidesteps it:

Surface Observed Expected
1 typeof proxy.then returns 'function' (same for .catch / .finally) 'undefined' (proxy should not advertise Thenable shape)
2 Promise.resolve(proxy) triggers .then() dispatch through the native bridge; plain objects unwrap cleanly via await Promise.resolve(plainObject) === plainObject proxy should behave like a plain object — no .then() bridge call
3 await proxy dispatches .then(resolve, reject) through the native bridge, producing UNIMPLEMENTED: "MyPlugin.then()" on web (and an indefinite hang on Android/iOS when the bridge silently swallows the unknown method) clean unwrap (no spec-Thenable detection)
The repo README also documents the production workaround pattern (container-wrap dynamic imports as { plugin: ... }) currently deployed at PlayOps Runtime as of 2026-05-16. Static import { Plugin } is immune to the bug; only dynamic-import-plus-Promise-chain patterns trip it, which is the canonical loader shape across the @capacitor-community/* ecosystem (admob, native-audio, cdv-purchase, etc.).

Suggested fix surface: registerPlugin()'s proxy get trap should special-case 'then' / 'catch' / 'finally' to return undefined. This is one localized change; no downstream consumer breaks because no plugin's public API legally exposes those names as methods. Detail + suggested patch shape in the repo README.

Happy to provide additional context on the production-side workaround if useful for triage.