diff --git a/docs/adr/BILLING-WEB-0031-static-spa-boundary.md b/docs/adr/BILLING-WEB-0031-static-spa-boundary.md index 545274447d6..e4ad3ef4557 100644 --- a/docs/adr/BILLING-WEB-0031-static-spa-boundary.md +++ b/docs/adr/BILLING-WEB-0031-static-spa-boundary.md @@ -37,6 +37,12 @@ The build output is a static SPA: item; transactional Subscribe, Resubscribe, and embedded-checkout actions remain in the core frontend until the hosted app reaches parity. + > **Amended 2026-09-27 by + > [ADR-BILLING-WEB-0038](BILLING-WEB-0038-checkout-only-hosts-own-plan-selection.md):** + > the flag no longer redirects Plans & pricing. Plan selection stays in + > the host app, which opens billing-web `/v1/checkout` with a `plan`; + > billing-web hosts checkout, not a plan grid. + The first scaffold deliberately does not guess the future SDK interfaces or credential lifecycle. Integration code must follow [ADR-AUTH-CREDENTIALS-0011](AUTH-CREDENTIALS-0011-cloud-credential-lifecycle-invariants.md) diff --git a/docs/adr/BILLING-WEB-0038-checkout-only-hosts-own-plan-selection.md b/docs/adr/BILLING-WEB-0038-checkout-only-hosts-own-plan-selection.md new file mode 100644 index 00000000000..9c6015c5642 --- /dev/null +++ b/docs/adr/BILLING-WEB-0038-checkout-only-hosts-own-plan-selection.md @@ -0,0 +1,94 @@ +# ADR-BILLING-WEB-0038: Billing Web Hosts Checkout Only; Host Apps Own Plan Selection + +Date: 2026-09-27 + +## Status + +Accepted + +## Context + +`apps/billing-web` grew two things for choosing a plan: a plan grid on +`/v1/subscription` and `/v1/pricing` (`SubscriptionPanel` plan cards and +`PlanCard`), and a plan-change quote (`SubscriptionQuote`). Neither had a +design source. They were built in #17798 and #17937 as scaffolding while +the hosted app worked toward parity with the cloud app, which already has +its own pricing table, Monthly/Yearly switch, plan-change flow, and team +credit-stop selection. + +The Milestone 2 live run on 2026-09-27 put the two side by side and found +the hosted copy had drifted from the in-app experience for the same +journey: yearly credits were labelled "monthly credits", and the +plan-change quote showed credits as a dollar amount. Each of these is a +small fix. The finding is that a second plan-selection UI with no design +source drifts by default, and every host that sends customers to +billing-web would carry that drift into the payment step. + +The embedded checkout is the opposite case. ADR-PACKAGES-ACCOUNT-UI-0034 +already puts payment presentation in `@comfyorg/account-ui` so that one +implementation serves every host. + +## Decision + +1. **billing-web hosts the embedded-checkout experience only**: the + payment step, the 3DS challenge, and the result. It renders the same + checkout UI as the cloud app's in-app embedded checkout, through the + shared components in `packages/account-ui`, not a restyled fork. + +2. **Plan selection belongs to each host app.** The pricing table, + Monthly/Yearly, plan changes, and the team credit stop are chosen in + the host, which then opens billing-web `/v1/checkout` with `plan`, and + with `workspace` and `team_credit_stop_id` where they apply. The team + credit stop behaves in billing-web exactly as in the in-app embedded + checkout. + +3. **`/v1/checkout` requires `plan`.** A plan-less `/v1/checkout`, and + `/v1/pricing`, redirect to the host app through `return_to` rather + than rendering a picker. The billing-web plan grid (`SubscriptionPanel` + plan cards, `PlanCard`, `SubscriptionQuote`) is removed. + +4. **The remaining routes stay.** `/v1/subscription` keeps cancel and + resubscribe, without the plan grid; the host app keeps its own cancel + and resubscribe too. `/v1/payment-methods`, `/v1/invoices`, + `/v1/result`, and `/sign-in` are unchanged. + +### Alternatives considered + +- **Polish the billing-web plan grid to match the app.** Rejected: it + keeps two implementations of one UX, and the drift found in the live + run is what that arrangement produces between releases. +- **Ask design for a separate billing-web plan-selection spec.** Rejected: + it gives one purchase journey two designed UXs, which is the divergence + this decision removes, now with a design source behind each side. + +## Consequences + +### Positive + +- A customer sees one plan-selection UI and one checkout UI whichever host + they start from. +- billing-web no longer needs plan catalogue, interval, or quote logic of + its own, so it has no copy of those to keep in step with the app. + +### Negative + +- A host without its own plan selection cannot send customers to + billing-web to pick a plan; it must build that UI or deep-link into a + host that has one. +- Rendering identically in both hosts means the shared components use + design-system token classes. That relaxes ADR-PACKAGES-ACCOUNT-UI-0034 + rule 4 ("the package stays unstyled"), amended there. +- Cancel and resubscribe exist in both billing-web and the host app, so + those two actions still have two surfaces to keep aligned. + +## Notes + +- [ADR-BILLING-WEB-0031](BILLING-WEB-0031-static-spa-boundary.md): its line + that the flag redirects Plans & pricing to billing-web is superseded by + rule 2 and carries an amendment note. +- [ADR-PACKAGES-ACCOUNT-UI-0034](PACKAGES-ACCOUNT-UI-0034-payment-ui-belongs-to-the-shared-account-ui-package.md): + rule 4 is amended to allow design-system token classes. +- [ADR-AUTH-BILLING-0032](AUTH-BILLING-0032-billing-stays-outside-the-account-package-in-v1.md): + rule 4 (no site-local billing surfaces) is the same principle applied to + `apps/website`; billing-web's checkout follows it through the shared + package. diff --git a/docs/adr/PACKAGES-ACCOUNT-UI-0034-payment-ui-belongs-to-the-shared-account-ui-package.md b/docs/adr/PACKAGES-ACCOUNT-UI-0034-payment-ui-belongs-to-the-shared-account-ui-package.md index cdb18bbe0e4..e0ac6c1feef 100644 --- a/docs/adr/PACKAGES-ACCOUNT-UI-0034-payment-ui-belongs-to-the-shared-account-ui-package.md +++ b/docs/adr/PACKAGES-ACCOUNT-UI-0034-payment-ui-belongs-to-the-shared-account-ui-package.md @@ -81,6 +81,13 @@ does not live in the package. framework-free above Vue; a promotion that drags the design system in has not finished. + > **Amended 2026-09-27 by + > [ADR-BILLING-WEB-0038](BILLING-WEB-0038-checkout-only-hosts-own-plan-selection.md):** + > promoted components may use `@comfyorg/design-system` token classes so + > the cloud app and `apps/billing-web` render the same checkout + > identically. Host couplings (`Button`, telemetry, journey events) still + > arrive as inputs. + 5. **Transport, commands and readers stay in `@comfyorg/account-core`.** This decision moves presentation only. It also does not make a surface shareable merely by moving it: state the frontend assembles from several diff --git a/docs/adr/README.md b/docs/adr/README.md index ebbc62ee97f..f7fc63b0712 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -22,6 +22,7 @@ An Architecture Decision Record captures an important architectural decision mad | [AUTH-WORKSPACE-0036](AUTH-WORKSPACE-0036-workspace-deep-link-contract.md) | Workspace Deep-Link Contract | Proposed | 2026-09-21 | | [BILLING-CHECKOUT-0031](BILLING-CHECKOUT-0031-checkout-journey-instrumentation-contract.md) | Checkout Journey Instrumentation Contract | Proposed | 2026-09-09 | | [BILLING-WEB-0031](BILLING-WEB-0031-static-spa-boundary.md) | Static SPA Boundary for Hosted Billing | Proposed | 2026-09-10 | +| [BILLING-WEB-0038](BILLING-WEB-0038-checkout-only-hosts-own-plan-selection.md) | Billing Web Hosts Checkout Only; Host Apps Own Plan Selection | Accepted | 2026-09-27 | | [CANVAS-GESTURE-0029](CANVAS-GESTURE-0029-pointer-gesture-state-machine.md) | Pointer Gesture State Machine | Proposed | 2026-09-06 | | [CANVAS-INTERACTION-0035](CANVAS-INTERACTION-0035-agent-node-picking-policy.md) | Agent Node Picking Policy | Proposed | 2026-09-19 | | [CANVAS-SELECTION-0028](CANVAS-SELECTION-0028-single-selection-store.md) | Single Selection Store | Proposed | 2026-09-04 |