chore: sync upstream PR #8256 - feat(core): export native bridge utility functions

[riderx]

Upstream PR Sync

This PR syncs changes from an external contributor's PR on the official Capacitor repository.

Original PR

• PR: #8256
• Title: feat(core): export native bridge utility functions
• Author: @sahilsharda

Automation

• CI will run automatically
• Claude Code will review for security/breaking changes
• If approved, this PR will be auto-merged

---

Synced from upstream by Capacitor+ Bot

Summary by CodeRabbit

• New Features

  • New Capacitor API methods: isRelativeOrProxyUrl() for URL validation and createProxyUrl() for URL proxy handling.

• Documentation

  • Added Android runtime setup, configuration, and local development guide.
  • Added iOS runtime setup, configuration, and local development guide.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Documentation for Capacitor Android and iOS runtimes was added, covering installation, usage, configuration, and compatibility. Two internal helper functions—isRelativeOrProxyUrl and createProxyUrl—were exposed as public API methods on the CapacitorInstance, with corresponding type definitions added.

Changes

Cohort / File(s)	Summary
Runtime Documentation android/README.md, ios/README.md	New documentation files added for Android and iOS runtimes, providing installation, usage, configuration, compatibility matrices, and development guidance.
Public API Exposure core/native-bridge.ts	Two internal helper functions assigned to cap.isRelativeOrProxyUrl and cap.createProxyUrl during bridge initialization, making them publicly accessible on the Capacitor instance.
Type Definitions core/src/definitions-internal.ts	Added two new method signatures to CapacitorInstance interface: isRelativeOrProxyUrl(url: string | undefined) => boolean and createProxyUrl(url: string, win: WindowCapacitor) => string.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Verification needed: Ensure isRelativeOrProxyUrl and createProxyUrl are appropriate for public exposure and do not introduce security or API stability concerns.
• Type alignment: Confirm that type signatures in definitions-internal.ts match the actual implementations and assignments in native-bridge.ts.
• Documentation files are low-risk and primarily require scanning for completeness and accuracy.

Poem

🐰 A bridge so fine, we now unfold,
Two helpers brave, no longer cold,
From internal depths to public light,
With docs so clear—Android, iOS bright!
The Capacitor grows, strong and free,
A URL journey, for all to see! 🚀

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title includes both a chore prefix and substantive feature content (exporting native bridge utility functions), which is reflected in the actual changes across multiple files including public API additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch sync/upstream-pr-8256

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

core/src/definitions-internal.ts (1)

93-101: New helper methods on CapacitorInstance tighten the type and may affect custom implementors

Adding isRelativeOrProxyUrl and createProxyUrl as required members is consistent with how initBridge wires them on the runtime instance, and it cleanly exposes the native-bridge helpers.

One nuance: because CapacitorInstance is now stricter, any custom platform/runtime code that structurally implements this interface may start failing type-checks until these methods are added. If you intend this to be purely additive for consumers, you might consider making these properties optional in the type (while still assigning them at runtime), or at least document the expectation for custom implementations.

core/native-bridge.ts (1)

125-138: Helper exposure matches existing bridge logic; be aware of createProxyUrl usage constraints

The new isRelativeOrProxyUrl and createProxyUrl helpers, and their exposure via cap.isRelativeOrProxyUrl / cap.createProxyUrl, align with the existing native-bridge.js implementations and with the internal uses in the fetch/XHR patches. This is a clean way to let plugins and app code reuse the same URL/proxy logic as the core bridge.

One subtle point: createProxyUrl builds its base with new URL(win.Capacitor?.getServerUrl() ?? ''). In standard native contexts getServerUrl() should be a valid origin, but if a consumer calls cap.createProxyUrl() in an environment where WEBVIEW_SERVER_URL is unset or non-URL (e.g., non-native/web usage), this can throw at runtime. That was already implicitly true for the internal use, but exposing it as public API makes external misuse more likely.

It may be worth:

• Documenting that createProxyUrl is intended for native/webview contexts where getServerUrl() is a valid URL, and/or
• Optionally short-circuiting to return the original URL when getServerUrl() is falsy/invalid, if you want a more defensive public helper.

Also applies to: 238-240

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 270d700 and bc202b1.

📒 Files selected for processing (4)

• android/README.md (1 hunks)
• core/native-bridge.ts (1 hunks)
• core/src/definitions-internal.ts (1 hunks)
• ios/README.md (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

core/native-bridge.ts (2)

ios/Capacitor/Capacitor/assets/native-bridge.js (2)

• isRelativeOrProxyUrl (144-144)
• createProxyUrl (146-154)

android/capacitor/src/main/assets/native-bridge.js (2)

• isRelativeOrProxyUrl (144-144)
• createProxyUrl (146-154)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: test-android
• GitHub Check: test-core

🔇 Additional comments (2)

ios/README.md (1)

1-75: iOS runtime README looks consistent and safe to merge

The installation, usage, configuration, and version-compat sections are clear and align with typical Capacitor iOS setup. No security or behavioral concerns from this doc-only addition.

android/README.md (1)

1-73: Android runtime README mirrors existing patterns with no behavioral impact

Install/add/run instructions, manifest/permissions guidance, version matrix, and resources look appropriate and match typical Capacitor Android usage. No security or breaking-change concerns.