Forms: refresh cached plan on editor return after plan purchase

[kraftbj]

Fixes FORMS-712 (Linear).

Proposed changes

The Forms file-upload field (and any other plan_check-gated editor block) kept showing its upgrade nudge after a plan purchase. Block availability (Jetpack_Editor_Initial_State.available_blocks) is computed server-side at editor render from Current_Plan::supports(), which reads the cached jetpack_active_plan option. That option is only refreshed by the daily jetpack_v2_heartbeat cron, and nothing refreshed it when the user returned from checkout — so the editor rendered the upsell from a pre-purchase plan while the "Congratulations" banner (driven by the ?plan_upgraded URL param) showed success. Simple/WordPress.com sites gate features live via wpcom_site_has_feature(), so they don't hit this; it's a self-hosted Jetpack / Atomic issue.

• Server (class.jetpack-gutenberg.php): in enqueue_block_editor_assets(), when the editor loads with ?plan_upgraded, refresh the plan from WordPress.com before block availability is computed, so the first post-checkout render is correct. Guarded to connected non-WPCOM sites, throttled to once per minute via a transient (a repeated/bookmarked ?plan_upgraded URL can't trigger a blocking request every load), and time-boxed to 5s so a slow origin can't hang the editor.
• Client (extensions/shared/plan-upgrade-notification.js): a one-shot reload fallback for the narrow race where WordPress.com finishes provisioning between the server refresh and the banner's own site fetch. It reloads once when the freshly fetched plan slug differs from the slug the page rendered with. The guard is keyed on the rendered plan slug and stored in sessionStorage through throw-safe helpers, and the reload only fires if the guard can be persisted first — so browsers with storage blocked/full (Safari private mode, blocked site data) can never enter a reload loop.
• Extracted shouldReloadAfterPlanUpgrade() as a pure function and added unit tests for it plus the IIFE orchestration (reload guard, error path, storage-throw, normal navigation).

Reviewed with a multi-persona code review + an independent adversarial pass; the two P2s they agreed on (unthrottled blocking refresh; sessionStorage throwing past optional chaining) are addressed above.

Related product discussion/links

• Linear: FORMS-712 — https://linear.app/a8c/issue/FORMS-712

Does this pull request change what data or activity we track or use?

No. The server refresh only re-fetches the site's own plan from WordPress.com (authenticated as the blog) into the existing jetpack_active_plan cache; no new data is collected or sent.

Testing instructions

Reproduces on a self-hosted Jetpack site connected to a WordPress.com account (e.g. a Jurassic Ninja site); it does not reproduce on Simple sites.

Baseline (before this change / on trunk):

• On a free Jetpack site, add a Form with a File upload field, save, and click Upgrade.
• Purchase a plan that includes file uploads (Jetpack Complete), and get redirected back to the editor.
• Note the "Congratulations" banner appears but the File upload field still shows the upgrade nudge until a manual reload / the next daily heartbeat.

With this change:

• Repeat the flow. On return from checkout the File upload field should no longer show the upsell on the first render (the server refreshes the plan before computing availability).
• If WordPress.com provisioning lags, the editor performs a single automatic reload and then shows the field unlocked. It must never reload more than once.

Quick mechanism check without a real purchase (WP-CLI on the connected site):

• wp option get jetpack_active_plan on a free site → the field-file block reports available:false, missing_plan.
• Set the plan to jetpack_complete and reload the editor → field-file reports available:true and the nudge is gone. (This is the exact state the server refresh produces on the ?plan_upgraded return.)

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the forms-712-forms-upsell-doesnt-go-away-after-plan-purchase branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack forms-712-forms-upsell-doesnt-go-away-after-plan-purchase

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

---

Jetpack plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

[jp-launch-control]

Code Coverage Summary

Coverage changed in 2 files.

File	Coverage	Δ%	Δ Uncovered
projects/plugins/jetpack/class.jetpack-gutenberg.php	268/553 (48.46%)	-0.98%	11 💔
projects/plugins/jetpack/extensions/shared/plan-upgrade-notification.js	35/41 (85.37%)	85.37%	-15 💚

Full summary · PHP report · JS report

_{Coverage check overridden by Coverage tests to be added later Use to ignore the Code coverage requirement check when tests will be added in a follow-up PR .}

[kraftbj]

@enejb — I dug into FORMS-712 and have a fix up here (draft for now, so we can test it on JN and via the beta plugin). Wanted to sanity-check the approach with you before taking it out of draft.

Root cause: on a self-hosted Jetpack (or Atomic) site, the editor decides whether a paid block like the Forms file-upload field shows its upsell from available_blocks, which is computed server-side at page render from the cached jetpack_active_plan option. That option only refreshes on the daily heartbeat cron — nothing refreshes it when you come back from checkout. So the "Congratulations" banner shows (it's driven purely by the plan_upgraded URL param), but the upsell is still drawn from the pre-purchase plan. That's why it's inconsistent — a reload, or the next day's heartbeat, clears it. Simple sites don't hit this because they gate features live via wpcom_site_has_feature() on every request, so the return-to-editor render already sees the purchase. That's the "different upgrade flow" you spotted.

The fix is two parts. Server: when the editor loads with plan_upgraded present, refresh the plan from WP.com before availability is computed, so the first render after checkout is correct (guarded to connected non-WPCOM sites, throttled to once a minute, and time-boxed so a slow WP.com response can't hang the editor). Client: a one-shot reload fallback for the narrow race where WP.com finishes provisioning between the server refresh and the page's own site fetch — if the freshly-fetched plan differs from what the page rendered with, it reloads once (guarded so it can never loop). Because it lives in the editor's availability layer, it covers every plan_check-gated block, not just Forms.

The honest caveat: if WP.com hasn't actually recorded the purchase yet when you land back in the editor (the "delay in sync" theory in the ticket), even a forced refresh gets the old plan and you'd still see the nudge until the next load. The reload catches a slightly-late provision, but a truly lagging WP.com is beyond what the site can fix locally. So this closes the structural gap and the common case; it's strictly better than today, but not a 100% guarantee in that pathological race.

One thing I didn't touch: the activity log dashboard you mentioned. That's a separate surface with its own caching, so it needs its own look — happy to investigate that separately if it's still happening.

Does this direction seem reasonable? If so, I'll double-check my work and take it out of draft for a real review.

[enejb]

A couple of things I noticed while testing this PR.
This Pr worked as expected for me.

They don't have to be fixed in this PR.

1. On the front end. The notice doesn't look as expected for me.

2. When I click on the View Plan in the notification that gets created on the Jetpack side I am taken to the following page.

I end up here.

This page is kind of hidden already from the regular Jetpack UI. It isn't accessible via the My Jetpack for example.

[enejb]

I find this really hard to read.

[enejb]

The code makes sense to me. I think we can ship this since it does improve things.

[kraftbj]

Thanks for testing this, @enejb! On the two things you flagged:

1. The collapsed front-end nudge is already fixed in Upgrade nudge: fix collapsed banner outside the block editor #50873.
2. The "View my plan" link landing on the hidden plan page is now tracked separately as FORMS-755.

Neither blocks this one — appreciate the review!