Skip to content

feat(ios): improve host integration, navigation, and canvas export - #266

Draft
DavidWu109 wants to merge 17 commits into
didi:mainfrom
DavidWu109:feat/ios-host-integration
Draft

feat(ios): improve host integration, navigation, and canvas export#266
DavidWu109 wants to merge 17 commits into
didi:mainfrom
DavidWu109:feat/ios-host-integration

Conversation

@DavidWu109

@DavidWu109 DavidWu109 commented Jul 20, 2026

Copy link
Copy Markdown

Summary

This PR groups the iOS host-integration work into focused commits while keeping one end-to-end review branch.

Host bridge integration

  • add app-scoped host API registration with explicit conflict policies
  • retain scoped API registrations when the same mini app is relaunched
  • return failure callbacks for unresolved asynchronous bridge calls
  • accept object render-bridge messages as well as serialized strings
  • keep built-in APIs on their existing registration path

Host UI and URL integration

  • add a host-provided page capsule extension point
  • add host URL scheme handler factories while protecting reserved schemes
  • use a dedicated dimina://sdk origin for SDK resources
  • keep mini-app file access confined to the corresponding app sandbox
  • accept positional and object parameter forms in synchronous storage APIs

Navigation behavior

  • parse page routes before navigation and preserve query precedence
  • report provisional WebView navigation failures
  • preserve root state across redirects and deep-linked entry pages
  • expose Home on non-root pages, including direct entry into a secondary page
  • hide Back and Home controls on the actual root page

Canvas export

  • add the iOS saveCanvasTempFile bridge used by canvasToTempFilePath
  • persist PNG and JPEG data URLs under the app temporary resource directory
  • return a Dimina virtual temporary-file path
  • add a render regression test proving export does not reset the source canvas resolution

Design notes

  • Host APIs implement DMPApiHandler; DMPBaseApiHandler provides an explicit name-to-handler registry.
  • Hosts register APIs and capsule providers on a specific DMPApp before launch.
  • API registrations survive relaunches of that app and are released when the app is destroyed.
  • JavaScript API enumeration and canIUse use the current app registry.
  • Name conflicts are rejected by default; .replace is required for an intentional override.
  • The capsule provider receives immutable page context and actions instead of internal controllers or WebViews.
  • Dimina owns capsule placement and sizing so native geometry remains consistent with getMenuButtonBoundingClientRect.
  • DMPPageRoute separates page paths from query values before state updates, resource lookup, and WebView configuration.
  • Custom URL schemes are validated; reserved dimina and difile schemes cannot be replaced.

Validation

  • Render test suite: 6 files, 46 tests passed
  • Xcode Debug build for a generic iOS Simulator with code signing disabled
  • Swift package and external-module type checks for the public host extension APIs
  • focused route parser checks covering multiple values, empty values, embedded equals signs, percent decoding, and explicit-query precedence
  • CocoaPods host-integration build with the EchoWebKit capsule provider

The simulator and host integration builds complete successfully. Existing upstream warnings remain unchanged.

Review note

This PR is intentionally kept as a Draft for joint review. Commits are split by responsibility so each concern can be reviewed independently before the PR is marked ready.

@dos1in

dos1in commented Jul 20, 2026

Copy link
Copy Markdown
Member

Thanks for the contribution and for the detailed validation provided in this PR. Two issues should be fixed before merging:

  1. [P1] Reject URL schemes handled internally by WebKit

    registerCustomSchemeHandler currently validates only the scheme format and excludes dimina and difile. As a result, WebKit-managed schemes such as http and https are accepted.

    WebKit throws an exception when setURLSchemeHandler is called for an internally handled scheme, causing subsequent WebView creation to crash.

    Suggested validation:

    guard !WKWebView.handlesURLScheme(normalizedScheme) else {
        return false
    }
  2. [P2] Pass the navigation bar background color to the host overlay

    DMPNavigationBarColorApplicable exposes a backgroundColor parameter, but DMPPageController.updateNavigationColor always passes nil.

    Therefore, the host-provided overlay cannot receive the actual background color from either the initial page configuration or wx.setNavigationBarColor.

    Please preserve and pass the original background color string through the call chain, or convert the UIColor before invoking the host callback.

@DavidWu109
DavidWu109 force-pushed the feat/ios-host-integration branch 2 times, most recently from 90559b0 to 26ec4f0 Compare July 20, 2026 07:44
@DavidWu109
DavidWu109 force-pushed the feat/ios-host-integration branch from 26ec4f0 to 853544e Compare July 20, 2026 08:03
@DavidWu109
DavidWu109 force-pushed the feat/ios-host-integration branch from 853544e to 9121657 Compare July 20, 2026 08:25
@dos1in

dos1in commented Jul 21, 2026

Copy link
Copy Markdown
Member

Thanks for the update—this P1 regression is introduced by the current PR because the new public custom-scheme API allows WebKit-handled schemes such as http and https, which can crash when registered.

@DavidWu109 DavidWu109 changed the title feat(ios): add host integration extension points feat(ios): improve host integration, navigation, and canvas export Jul 21, 2026
@DavidWu109
DavidWu109 marked this pull request as draft July 21, 2026 06:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants