Constraints of mini-programs inside super-apps

What it is

A mini-program inside WeChat, Alipay, or Douyin is not a full standalone app. It is a guest inside a super-app. The host owns the window chrome: the top-right capsule (more, close), sharing, forwarding, payment, and sign-in. The guest runs in a page stack, API allowlist, and lifecycle the host draws—it can be killed at any time, cannot replace the capsule, and cannot bypass the host to raise its own payment sheet or system share sheet. These are architectural platform requirements, not the guest’s visual taste.

This is which sovereignty the guest lacks relative to the host, not a comparison of Mainland versus international discovery, QR entry, or services-in-chat. Designing a mini-program as if it could take over the screen and paint a navigation bar that fights the host will be clipped on device.

Why it happens

Sovereignty is split in two. Window-level close, the more menu, and the strip that overlaps the status bar are drawn and hit-tested by the host; the guest lays out only in the remaining content region. Share and forward go through the host sheet because distribution happens on the host’s social graph; the guest has no friend list of its own to write. Sign-in and payment go through host APIs because credentials and money accounts live on the host—the guest receives a token and a result code, not a password, not a card number.

Stack depth, background lifetime, and which device capabilities may be called are capped so the super-app itself remains a process the OS can schedule, rather than being dragged into a resident operating system by its guests. If the guest paints its own bar to “cover” the capsule, or draws a fake close control, hit-testing still lands on the host; the user gets the host’s close, not the guest’s back. On the lifecycle, the host may destroy the guest when it is not visible: state not written through the host storage API will not be there on return.

Where it stops holding

Some mini-programs appear as half-sheets, live-room overlays, or scan-and-go surfaces with almost no stack; the constraint still holds: the capsule or the host’s close remains the exit. An H5 page embedded in a standalone app is not a mini-program—it is free of the capsule model, and it also does not automatically receive the host’s payment or social graph. Allowlists and share sheets differ across WeChat, Alipay, and Douyin; a capability permitted in one host must not be assumed to pass in another. Desktop super-app windows can look closer to independent windows, but identity and payment still run through the host—that is not a license to demand system-level permissions.

Applying it

• Treat navigation, close, and share as part of the host chrome: leave the top-right capsule unoccupied, put primary actions in the content region, and do not draw a close control that fights the capsule for hits.
• Run sign-in, payment, and share only through host APIs and sheets. Request user data within the host’s authorization scopes; do not build a parallel username-and-password form on the guest page.
• Persist critical state through host-allowed storage, and design recovery as if the guest can be destroyed at any time, rather than assuming it stays resident.
• Verify in the real host: open the mini-program, use the capsule’s more and close, run one host share and one host payment (or sandbox), then background the mini-program long enough to be killed and return. A drawn close that does nothing, a share sheet that is not the host’s, a blocked payment, or a missing draft on return all mean the guest treated host sovereignty as its own.

Related

• Same group: R4.04.1 Distributed continuation across devices · R4.04.3 Points of divergence from international platform conventions · R4.04.4 Multi-end deployment requires layout by capability, not screen name · R4.04.5 Service cards surface functions at the desktop layer · R4.04.6 System-owned identity and payment change flow boundaries
• Adjacent: R4.06 Platform convention versus brand consistency · R4.07 App store review
• Search terms: mini-program · super-app · host chrome · capsule button