fix: preserve vendor API method receivers

[harlan-zw]

Linked issue

• fix(scripts): preserve vendor method receivers unjs/unhead#907
• Sentry issue NUXTSEO-SITE-17

Type of change

• Bug fix
• Feature
• Documentation
• Refactor

Description

Methods returned by use() can run with Unhead's forwarding proxy as this. Firefox then rejects native DOM calls such as JSConfetti's canvas getBoundingClientRect() call.

Wrap synchronous and Promise based use() results with stable, receiver safe method proxies before passing them to Unhead. This includes Promises created in another browser realm. Unit and Nuxt runtime tests cover the failures. This protects Nuxt Scripts users on supported Unhead releases while the root fix lands upstream.

Verification

• pnpm lint
• pnpm typecheck
• pnpm build
• pnpm test:run, 963 tests passed

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
scripts-playground	Ready	Preview, Comment	Jul 23, 2026 1:24pm

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/scripts@843

commit: e8de87f

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds bindScriptApiMethods and bindScriptApiResolver to preserve script API method receivers, cache wrappers, support construction, and handle synchronous or Promise-based resolver results. Client-side useScript now wraps provided options.use resolvers. Unit and Nuxt runtime tests cover receiver preservation, stable method identity, cross-realm resolution, and branded API invocation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly matches the main change: preserving vendor API method receivers.
Description check	✅ Passed	The description is directly related to the receiver-safe method proxy fix and the added tests.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/vendor-api-receivers

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/script/src/runtime/script-api.ts`:
- Around line 61-63: Update the result handling around bindScriptApiMethods to
detect Promises across browser realms using the standard Promise tag rather than
instanceof Promise. Preserve direct binding for non-Promise results, and apply
result.then(bindScriptApiMethods) for both same-realm and cross-realm Promises.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ac4959a7-3872-4068-ae1b-6242a5e05bc2

📥 Commits

Reviewing files that changed from the base of the PR and between 8a2c985 and 14e4af0.

📒 Files selected for processing (4)

• packages/script/src/runtime/composables/useScript.ts
• packages/script/src/runtime/script-api.ts
• test/nuxt-runtime/proxy-receiver.nuxt.test.ts
• test/unit/script-api.test.ts