Skip to content

FE-3018 feat(billing-web): inline Pay outcomes, collided-Pay backstop and reactivation on the full-page checkout - #19264

Merged
dante01yoon merged 6 commits into
jaewon/fe-3018-saved-methods-railsfrom
jaewon/fe-3018-rails-and-outcomes
Sep 29, 2026
Merged

dante01yoon merged 6 commits into
jaewon/fe-3018-saved-methods-railsfrom
jaewon/fe-3018-rails-and-outcomes

Conversation

@dante01yoon

@dante01yoon dante01yoon commented Sep 28, 2026 •

Copy link
Copy Markdown
Collaborator

Why

FE-3018 (Milestone 3, checkout guidebook 1). On the full-page checkout a Pay that failed showed nothing and left Pay locked, a Pay that collided with another operation would have read as a failure, and a cancelled subscriber could not confirm the reactivation charge. This PR adds the inline outcome cards from Figma 345-14026 / 314-10555, the race backstop from the rule set, and the reactivation confirm the embedded view already has. Second half of FE-3018 PR 2, stacked on #19263.

Root cause

n/a, feature.

How

  • The CheckoutPage capture state gains reactivation: 'not_required' | 'required' | 'invalid' | 'confirmed' and an optional outcome: declined (with the decline reason and operation id), processing_error, not_completed, price_updated, or reconciling. New events: paySubmitted, payFailed, payRejectedAsPending, requoted, reactivationConfirmed, consentMissing.
  • Rules in the reducer:
    • paySubmitted clears the card; the card otherwise persists.
    • payFailed sets the card and never touches the rail, so the Stripe element is not remounted and typed details survive. Pay stays "Pay and subscribe".
    • reconciling locks Pay, and every later Pay-side event is ignored until PR 3 re-reads the operation.
    • Pay stays live over an unticked keep-subscription consent. consentMissing (Pay clicked without the tick) marks it invalid; ticking clears it; a re-quote resets the tick, as the embedded view does on each new preview.
  • payVerdictOf (pure) maps a SubscriptionCommandResult to what the page does:
    • A settled operation goes through projectPaymentStep (account-core). declined with reason authentication_failed is Payment not completed (one card for a 3DS refusal and a redirect back-out, D1), other declined keeps its reason, processing_error (including reconciliation_needed) is the processing card. Nothing is derived from action_url.
    • timed_out (an unknown outcome, rule 12), OPERATION_ALREADY_PENDING and CONFLICT become reconciling, never a decline (rule 18).
    • serverCode PRORATION_QUOTE_EXPIRED or SUBSCRIPTION_QUOTE_STALE (checked through matchesServerCode, before CONFLICT) re-quotes and shows "The price has updated".
    • REACTIVATION_CONFIRMATION_REQUIRED re-quotes and asks, as CheckoutView.vue does.
    • Any other code keeps PR 1's coded failure line.
  • After a card outcome the composable calls checkout.reset() so the failed operation stops locking Pay.
  • Keep-subscription consent (Figma 553-9297) replaces the embedded reactivation copy. It is asked when the quote says requires_reactivation_confirmation or the server answers REACTIVATION_CONFIRMATION_REQUIRED (server-driven, never derived here). KeepSubscriptionNotice is a notice card above Pay with a native checkbox styled as the shadcn one: title "Your plan was set to end on {date}" (the date is cancel_at from /billing/status, read only once a quote asks), body from checkout/keepSubscription.ts by change type (upgrade, downgrade, monthly to yearly, yearly to monthly, team commitment, else a neutral line) with the amount and date the quote reports for the renewal, never computed here. Pay without the tick submits nothing (the click is intercepted in CheckoutPayAction, and pay() refuses a token the form hands over), puts the checkbox in its Invalid state (aria-invalid, red line "Check the box to keep your subscription, then pay." wired by aria-describedby) and focuses it. With the tick, Pay sends confirm_reactivation: true through the shared buildSubscribeRequest.
  • InlineOutcomeCard is the shared notice style: rounded-lg p-4 bg-tertiary-background, 8px gap, circle-alert in text-warning-background, medium title, every line 14/20, and for a decline the mapped line "Reported issue: {reason}". It is role="alert", and it scrolls into view and takes focus when it mounts.
  • A ghost "Contact support" sits under Pay only alongside a card that carries a failed operation (declined, processing, not completed); a notice over a fresh price never gets one. It is a mailto:support@comfy.org whose body names the operation id and the decline code.
  • Design review (Alex 2026-09-28): keep-subscription checkbox replaces the reactivation confirm (Pay live, Invalid state on a click without the tick); notice card style (tertiary-background, medium title, 14/20, rounded-lg); no Contact support under the price-updated card; D1 "Payment not completed" replaces "Payment not verified". Screenshots below recaptured.
  • reconciling renders the payment-column skeleton with Pay disabled; PR 3 replaces it with the reconciled state.
  • pay is split into requestFor and settle to stay under the fallow complexity gate.

Tradeoffs

  • The decline reason line uses new billing-web strings keyed by PaymentReasonKey (the account-core type), because the core's default copy is full sentences ("Your bank reported insufficient funds.") and Figma wants a short label after "Reported issue:".
  • No support-link builder existed that carries an operation id (CheckoutSteps uses a bare mailto:), so supportLinkFor is new and local.
  • A server 409 with no known code is treated as a collision (reconciling), not a decline. If the server ever uses 409 for a genuine refusal, the customer sees the skeleton until PR 3 reconciles instead of a coded line.
  • Promo expired is left to FE-3020.

Blast Radius

Only billing_web_checkout_ui = full_page. The embedded CheckoutView.vue, CheckoutPayment.vue and CheckoutSubmit.vue are untouched. No package code changes.

Verification

  • pnpm --filter @comfyorg/billing-web typecheck: clean.
  • pnpm --filter @comfyorg/billing-web test:unit: 27 files, 353 tests pass.
    • payVerdict.test.ts tables 13 SDK results to their verdicts, plus the support link.
    • checkoutPage.test.ts adds the post-Pay table, a rail-identity check on decline, and a reconciliation-hold table.
    • FullPageCheckoutView.test.ts adds decline (card, reason, focus, support link with op id and code, form mounted once, cleared on the next Pay), verification and processing cards, both backstop codes (no card, Pay locked), quote expired, and reactivation from the quote and from the server.
  • Mutation check, each turned a test red: remounting the element on decline, keeping the card on the next Pay, not locking Pay while reconciling, not holding reconciliation against later events, not locking on an unticked reactivation, rendering CONFLICT as a decline, reading a failed verification as a decline, not re-pricing a stale quote, not dismissing the failed operation, not sending confirm_reactivation, dropping the op id from the support link, and not focusing the card.
  • CI=1 pnpm exec playwright test in apps/billing-web (fresh production build): 38 passed.
    • New: a declined subscribe (decline_reason: insufficient_funds) shows the card and reason, Pay "Pay and subscribe" enabled, and Contact support carrying op_subscribe and the code.
    • New: a pending_billing_op_id already on /billing/status makes the lifecycle refuse with OPERATION_ALREADY_PENDING; no decline card, no support link, Pay disabled, and no /billing/subscribe request.
  • pnpm --filter @comfyorg/billing-web lint, oxfmt and oxlint on changed files, pnpm knip, and the pre-push fallow:audit: clean.
  • After the design review: keepSubscription.test.ts tables the body per change type and the undated title; KeepSubscriptionNotice.test.ts covers the three states, the focus hand-off on Invalid and the emits; the reducer table has the consent rows (Pay live while asked, consentMissing marks invalid, tick clears, untick re-asks, re-quote re-asks, consent nobody asked for); FullPageCheckoutView.test.ts drives Pay without the tick (no subscribe, aria-invalid, focus, described-by), then with it (confirm_reactivation: true), a token handed over without the tick, and the server re-ask with Pay live. full-page-checkout.spec.ts adds 553-9297 end to end: Pay without the tick sends no /billing/subscribe and marks the box invalid, the tick sends confirm_reactivation. 390 unit tests and the checkout spec pass at this head.

BE gaps / design questions

  • BE gap: the quote-expired refusals (PRORATION_QUOTE_EXPIRED, SUBSCRIPTION_QUOTE_STALE) have no coded SDK result; they are matched by serverCode. Their HTTP status is not in the contract.
  • Design D1 (decided 2026-09-28): one "Payment not completed" card for 3DS and redirect back-outs, Figma 340-13834.
  • Design (decided 2026-09-28): no Contact support under the price-updated card; the rule wins and the frame was updated.
  • Design question: two keep-subscription strings are not in DES-1209's 2026-09-28 copy. titleUndated "Your plan was set to end" renders while /billing/status has not yet answered with cancel_at, and body.other "This change keeps your subscription, and it renews that day at {amount}." covers a new_subscription quote that still asks for consent. Both are placeholders pending design copy; the five DES-1209 bodies and the dated title are verbatim.

AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake Stripe) at 1512x982 with full_page on. The fake Stripe mounts no real element, so the card and address areas are empty. AS IS is the base branch (PR 1).

AS IS: a declined Pay shows nothing and leaves Pay locked TO BE: declined card with reason, Pay unchanged, Contact support
as-is declined declined
TO BE: processing error TO BE: Payment not completed (340-13834)
processing error not completed
TO BE: keep subscription, asked (553-9297) TO BE: Pay clicked without the tick TO BE: ticked
keep subscription invalid ticked

Where this sits in the plan

One linear stack on main: each PR is based on the one above it in the table. The former FE-3019/FE-3020 sibling stack now sits on top of FE-3022.

Step PR Scope
FE-3067 #19248 (merged) flag and variant switch
FE-3018 PR 0 #19252 page state union and pure transition
FE-3018 PR 1 #19253 shell, eyebrow, capture skeleton
FE-3018 PR 2a #19263 saved-method tabs, rail failure taxonomy
FE-3018 PR 2b this PR inline Pay outcomes, backstop, reactivation
FE-3018 PR 3a #19268 mount reconciliation, placeholders
FE-3018 PR 3b #19271 bfcache and cross-tab re-reconciliation
FE-3021 PR 1 #19279 success, already completed, in progress, received, unconfirmed
FE-3021 PR 2 #19280 refusal, plan not available, couldn't load
FE-3022 #19285 two-phase submit area, 3DS re-open, redirect methods, verification failed
FE-3019 PR 1 #19266 summary ledger model and builder
FE-3019 PR 2 #19267 left-column ledger rendering
FE-3020 1/3 #19276 discount rows, fold rule, Subtotal
FE-3020 2/3 #19277 promo entry state, Pay binding, URL promo
FE-3020 3/3 #19278 promo entry UI, chips, expired card
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19264 stroke-width:3px
Loading

@dante01yoon
dante01yoon requested a review from a team as a code owner September 28, 2026 18:14
@dante01yoon dante01yoon added needs-backport Fix/change that needs to be cherry-picked to the current feature freeze branch core/1.55 Backport PRs for core 1.55 cloud/1.55 Backport PRs for cloud 1.55 labels Sep 28, 2026
@coderabbitai

coderabbitai Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: Comfy-Org/ComfyUI_frontend/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: af480adc-0583-4c06-b6ea-b3db4efa156b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

🧩 Custom Nodes Ecosystem Matrix: ✅ Passed

Executes the frontend JS of every registry pack that ships any, against this change, in both renderers. The eight ecosystem-matrix shard checks are a harness self-test; the pack verdict is matrix-verdict.

Stage Result What a failure here means
pin-status success Informational. It never fails the build; it warns when the corpus snapshot is over 30 days old.
corpus success Infrastructure: the pack mirror could not be fetched, validated or cached. Not your diff.
shards success Harness integrity, not pack breakage. A shard only checks that every built spec wrote its row; vitest's own exit code is deliberately ignored because pack code leaks unhandled rejections.
verdicts success The population verdict per renderer. This is the stage that judges packs. Exit 1 is FAIL; exit 2 is withheld — rows were missing, so nothing was measured, which is not the same as your change breaking packs.
detection-proofs success The instrument self-test: the matrix must FAIL on a deliberately poisoned corpus. A failure here means the gate cannot be trusted this run, in either direction.

On a pin-bump PR, a red gate means the ecosystem moved — not that your diff broke something. That is what the bump PR is for. Outside a pin bump or a cold rebuild of the unpinned tail, a red means the diff.

Note the corpus size and the executed count are different numbers, and the verdict is against the executed count: roughly 3,100 of ~5,100 packs ship no extension-shaped JS and are skipped.

Reproduce locally
# build one shard's fixture, then run it
python3 scripts/registry-census/build_matrix.py --shard 1/4
MATRIX_RENDERER=vue MATRIX_VUE=1 \
  npx vitest run --config vitest.matrix.config.mts

Full docs: scripts/registry-census/README.md

📦 Bundle Size

⏳ Size data collection in progress…

🌾 Fallow: ✅ Passed

Fallow audits the diff for duplication, complexity and dead code. It gates on new findings only, so when the audit completes, a red is something this PR introduced or moved — never inherited backlog. A red can also mean the audit itself did not finish; the details below say which happened.

No new findings in the changed files.

Reproduce locally
# the base the gate compared against
npx fallow audit --root . --quiet --format json \
  --changed-since 69eca0f45b9539af2837b477092030a28bcd6593

Full docs: ADR-DEVEX-LINT-0015

🎭 Playwright: ✅ 2159 passed, 0 failed

📊 Browser Reports
  • chromium: View Report (✅ 2138 / ❌ 0 / ⚠️ 0 / ⏭️ 9)
  • chromium-2x: View Report (✅ 2 / ❌ 0 / ⚠️ 0 / ⏭️ 0)
  • chromium-0.5x: View Report (✅ 1 / ❌ 0 / ⚠️ 0 / ⏭️ 0)
  • mobile-chrome: View Report (✅ 18 / ❌ 0 / ⚠️ 0 / ⏭️ 0)
  • New-test walkthrough (chromium, recorded video): View Report

🌐 Website E2E

Tip

All tests passed.

Status ✅ Passed
Report View Report

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 09/29/2026, 06:18:22 AM UTC

Links

@github-actions github-actions Bot added the risk:xhigh PR risk grade (advisory shadow check; grader-owned) label Sep 28, 2026
@codecov

codecov Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.72764% with 32 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
...billing-web/src/composables/useFullPageCheckout.ts 94.90% 0 Missing and 8 partials ⚠️
apps/billing-web/src/checkout/operationChannel.ts 89.36% 4 Missing and 1 partial ⚠️
...ps/billing-web/src/composables/useCheckoutPromo.ts 82.14% 0 Missing and 5 partials ⚠️
apps/billing-web/src/checkout/checkoutPage.ts 97.16% 0 Missing and 3 partials ⚠️
.../src/components/fullPage/CheckoutPaymentColumn.vue 93.33% 0 Missing and 2 partials ⚠️
...pps/billing-web/src/views/FullPageCheckoutView.vue 92.00% 0 Missing and 2 partials ⚠️
apps/billing-web/src/App.vue 80.00% 0 Missing and 1 partial ⚠️
apps/billing-web/src/checkout/payVerdict.ts 97.43% 0 Missing and 1 partial ⚠️
apps/billing-web/src/checkout/summaryLedger.ts 98.68% 0 Missing and 1 partial ⚠️
...ing-web/src/components/fullPage/CheckoutEnding.vue 96.96% 0 Missing and 1 partial ⚠️
... and 3 more
@@                          Coverage Diff                           @@
##           jaewon/fe-3018-saved-methods-rails   #19264      +/-   ##
======================================================================
+ Coverage                               84.25%   84.30%   +0.04%     
======================================================================
  Files                                    3244     3257      +13     
  Lines                                  157264   157958     +694     
  Branches                                42681    41040    -1641     
======================================================================
+ Hits                                   132506   133161     +655     
- Misses                                  23043    23059      +16     
- Partials                                 1715     1738      +23     
Flag Coverage Δ
billing-web-unit 91.63% <95.70%> (+2.40%) ⬆️
unit 81.51% <100.00%> (ø)
website-unit 78.72% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
apps/billing-web/src/checkout/cloudLinks.ts 100.00% <100.00%> (ø)
apps/billing-web/src/checkout/endingScreen.ts 100.00% <100.00%> (ø)
apps/billing-web/src/checkout/keepSubscription.ts 100.00% <100.00%> (ø)
apps/billing-web/src/checkout/promoEntry.ts 100.00% <100.00%> (ø)
apps/billing-web/src/checkout/subscribeRequest.ts 73.33% <100.00%> (+1.90%) ⬆️
...-web/src/components/fullPage/CheckoutPayAction.vue 100.00% <100.00%> (ø)
.../src/components/fullPage/CheckoutSummaryColumn.vue 100.00% <100.00%> (ø)
...-web/src/components/fullPage/InlineOutcomeCard.vue 100.00% <100.00%> (ø)
...src/components/fullPage/KeepSubscriptionNotice.vue 100.00% <100.00%> (ø)
...ng-web/src/components/fullPage/PaymentTabsRail.vue 100.00% <100.00%> (ø)
... and 17 more

... and 11 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@dante01yoon
dante01yoon force-pushed the jaewon/fe-3018-rails-and-outcomes branch from fc256aa to b713ab9 Compare September 28, 2026 18:17
@dante01yoon
dante01yoon force-pushed the jaewon/fe-3018-saved-methods-rails branch from 17fb796 to 0da76e0 Compare September 28, 2026 22:11
@dante01yoon
dante01yoon force-pushed the jaewon/fe-3018-rails-and-outcomes branch from b713ab9 to 1a92aae Compare September 28, 2026 22:11
@comfydesigner

Copy link
Copy Markdown
Contributor

A few design updates affect this PR: the notice card style, the reactivation checkbox (Pay should stay live), and the answer on Contact support under the price-updated card. Details are in the #proj-billing thread and on FE-3018.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Blocker: keep Pay enabled when reactivation consent is unticked. An unticked submit must send no billing request and move the checkbox to its invalid state with the red validation line. The current reducer makes reactivation === 'required' fail railAcceptsPay, so the disabled button cannot produce that validation state.
  • Blocker: use the new keep-subscription consent copy per change type. The current text confirms an {amount} charge to reactivate, but the plan may not have ended and some changes charge nothing today.
  • The verification outcome still uses the superseded bank-specific “Payment not verified” copy. Use the decided generic “Payment not completed” treatment shared by card authentication and redirect-method cancellation.
Full context for agent readers

These requirements are now recorded on full-page checkout flow and entry and payment authentication. Preserve the existing collision backstop and rail state while changing the consent interaction: clicking Pay without consent is a local validation event, not a disabled control and not a subscribe attempt.

@dante01yoon

Copy link
Copy Markdown
Collaborator Author

The 23:18Z blocker is implemented in 15158d9, the keep-subscription consent commit at this head. An unticked consent keeps Pay live now. railAcceptsPay no longer gates on the consent. Clicking Pay unticked dispatches consentMissing, which moves the checkbox to invalid with the red line and sends no billing request. Tests cover this in checkoutPage.test.ts ("Pay without the tick marks the consent invalid, Pay still live") and in FullPageCheckoutView.test.ts (553-9297, "a token the form hands over without the tick sends nothing either", and "re-quotes and asks unticked ... with Pay still live").

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed exact head fed2706a8e1564e39b2745efc2d450a02ba9c1e8 against the declared stacked base jaewon/fe-3018-saved-methods-rails (69eca0f45b9539af2837b477092030a28bcd6593). The previous consent/copy/“Payment not completed” blockers are addressed, and the focused tests pass.

  • Blocker: handle a failed mandatory re-quote instead of silently restoring Pay over the stale quote. In apps/billing-web/src/composables/useFullPageCheckout.ts:240-241, a quote-expired or reactivation-required response calls quoteArrival, then simply returns when that request fails. usePreviewSubscribe keeps the previous preview on ordinary failures, canPay becomes true again once submission ends, and payFailure intentionally hides the original error because its verdict is requote. The page therefore shows neither the re-quote failure nor a price-updated/consent state and lets the customer repeatedly submit the stale price. Please transition to an explicit unavailable/retry state (or otherwise surface and gate the failed re-quote), and add a view/composable regression test for both re-quote reasons with a failed previewSubscribe response.

Evidence: billing-web typecheck and lint passed; 5 focused Vitest files passed (131 tests); the focused full-page checkout Playwright spec passed (8 tests); CI checks shown on the PR are green. The full billing-web unit run encountered a local Vitest worker-termination hang after test execution, so I reran the changed suites with two workers. Cross-model adversarial review was unavailable after the documented cascade (Gemini trust/skill-conflict failure, Qwen unauthenticated, Claude hook failure, Amp no usable output); no same-model substitute was used.

…ote fails

A quote-expired or reactivation-required Pay verdict re-quotes before Pay
can run again. When that re-quote failed, the page stayed in capture over
the refused price with Pay live and nothing shown. The failure is now a
named requoteFailed event that moves capture to unavailable with the
failure's code.
@dante01yoon

Copy link
Copy Markdown
Collaborator Author

Addressed in 6330cc9.

  • A failed mandatory re-quote is now a named reducer event, requoteFailed { code }, which moves capture to the existing unavailable page. Pay is gone rather than live over the refused price, and the failure's code is shown. settle hands the re-quote to a requote helper that dispatches either requoted or requoteFailed.
  • Tests: FullPageCheckoutView.test.ts covers both reasons (expired quote, server-required consent) with a failed previewSubscribe. It asserts the failure copy, no Pay button, and exactly one subscribe. The reducer table covers the transition from a live capture and from an unticked consent, and that it is ignored outside capture. With the dispatch removed, both view cases fail.
  • Up the stack, FE-3021 feat(billing-web): full-page checkout refusal and load-failure screens #19280's couldn't-load screen adds Try again. 5213161 updates the same view test there to assert the "Couldn't load your checkout" heading and the code. It also clicks Try again and checks that the page quotes again in place.

The rest of the stack is rebased. billing-web typecheck, unit tests, lint, knip and the fallow audit against each PR base pass at every changed head. At the tip, the billing-web Playwright suite passes (68 tests).

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved at 6330cc9083d25191dc8d4223febf94f254627c4e against the declared stacked base jaewon/fe-3018-saved-methods-rails (69eca0f45b9539af2837b477092030a28bcd6593).

The failed mandatory re-quote blocker is addressed for both an expired quote and server-required reactivation consent. A failed fresh quote now leaves capture for the existing unavailable screen, removes Pay over the refused price, surfaces the failure code, and sends no second subscribe request. The added reducer and view tests cover both reasons.

Evidence: billing-web typecheck and lint passed; 5 focused Vitest files passed (136 tests); the focused full-page checkout Playwright spec passed (8 tests). CI has no reported failures; the billing-web jobs were still running at review time. An independent cross-model pass was unavailable after all configured providers failed, so no same-model substitute was used.

dante01yoon added a commit that referenced this pull request Sep 29, 2026
… checkout (2/3: entry state and quote binding) (#19277)

## Why

FE-3020 part 2 of 3, stacked on
#19276. It adds the
pure pieces the promo entry needs before any UI: a place for a promo
code on the entry URL, one state machine for the entry, and a Subscribe
that echoes the code its quote was priced with. Without that echo,
billing's quote revalidation (`EqualFold(quote.PromotionCode,
req.PromotionCode)` in `subscription_quote.go`) answers
`SUBSCRIPTION_QUOTE_STALE` to every Pay on a promo quote.

## Root cause

n/a, feature.

## How

- `@comfyorg/billing-contract`: a new optional entry field
`promotionCode`, carried as the `promo` query param. It is one more row
in `OPTIONAL_ENTRY_FIELDS`, with the shared identifier charset and the
code `INVALID_PROMOTION_CODE`. The contract still carries no price. The
code only prefills a field that the customer applies (DES-1088:
"prefill, never apply").
- `checkout/promoEntry.ts` is a pure module.
- `PromoEntry` is `idle | editing(draft) | applying(draft) |
rejected(draft, reason) | applied(code) | removing(code)`.
- `reducePromoEntry` ignores any event that means nothing in the current
state, so a late answer for an abandoned apply changes nothing.
- `promoRejectionOf` reads `PROMOTION_CODE_INVALID` and
`PROMOTION_CODE_INAPPLICABLE` as `invalid`. Every other failure is
`unchecked`: the code was never judged.
- `promoEntryLive` is the quote-binding lock. Entry is live only in
capture, with no Pay in flight and no collided Pay being reconciled.
- `checkoutPage.ts`: two small additions, a `promo_expired { code }`
inline outcome and an optional `expiredPromo` on `requoted`. A lapsed
code outranks `price_updated`.
- `subscribeRequest.ts` sends `promotion_code` whenever the quote
carries one.

## Tradeoffs

- A malformed `promo` value refuses the whole entry URL, like every
other optional field. Real Stripe codes fit the charset. A per-field
"drop and continue" rule would break the table's one rule for all
fields.
- `applied` lives in the machine even though the quote also carries the
code. The chip renders from the quote. The machine uses it to hide the
entry at the cap and to re-quote with the code at Pay.

## Blast Radius

- The contract change is additive. Existing entry URLs parse unchanged.
- `promotion_code` on Subscribe is sent only when the quote has one.
Nothing on billing-web quotes a code until part 3, so both checkouts
send the same body as today.

## Verification

- `pnpm --filter @comfyorg/billing-contract test`: 75 pass. The
round-trip now includes `promo=LAUNCH20`, and `SAVE 20` is refused with
`INVALID_PROMOTION_CODE`.
- `pnpm --filter @comfyorg/billing-web test:unit`: 409 pass.
- `promoEntry.test.ts` has a 15-case transition table: apply ok, invalid
at Apply keeps the typed value, typing clears the error, an empty field
does not apply, the URL prefill opens unapplied and can be dismissed,
remove, a failed remove, expired at Pay, the cap blocks a second code, a
late answer, and a locked field while applying.
- It also covers rejection reads and the lock table: capture live;
locked with Pay in flight, while reconciling, and before the quote.
- `checkoutPage.test.ts`: a `requoted` event with `expiredPromo` leaves
the `promo_expired` card and Pay live.
- `subscribeRequest.test.ts`: a promo quote echoes `promotion_code`
beside `quote_id`.
- Mutation check: dropping the in-flight guard from `promoEntryLive`
fails its table case, and dropping the `promotion_code` echo fails the
request case.
- Typecheck, lint, `pnpm knip` and the pre-push fallow audit: clean.

## BE gaps / design questions

- BE gap: no distinct "expired" code at preview. An expired code arrives
as `PROMOTION_CODE_INVALID`, so "This code has expired." cannot be told
apart from "This code isn't valid." at Apply.
- BE gap: a code that lapses after Apply surfaces at Subscribe only as
`SUBSCRIPTION_QUOTE_STALE`. Part 3 infers the lapse by re-quoting with
the code and getting `PROMOTION_CODE_INVALID`. A typed
`PROMOTION_CODE_EXPIRED` on Subscribe would remove that inference.
- Contract question: should a bad `promo` value drop just the prefill
instead of refusing the entry?

## AS IS / TO BE

No visible change in this part. The UI lands in part 3.

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| FE-3018 PR 2a |
#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
#19268 | mount
reconciliation, placeholders |
| FE-3018 PR 3b |
#19271 | bfcache and
cross-tab re-reconciliation |
| FE-3021 PR 1 |
#19279 | success,
already completed, in progress, received, unconfirmed |
| FE-3021 PR 2 |
#19280 | refusal, plan
not available, couldn't load |
| FE-3022 | #19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| FE-3019 PR 1 |
#19266 | summary
ledger model and builder |
| FE-3019 PR 2 |
#19267 | left-column
ledger rendering |
| FE-3020 1/3 | #19276
| discount rows, fold rule, Subtotal |
| **FE-3020 2/3** | **this PR** | **promo entry state, Pay binding, URL
promo** |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19277 stroke-width:3px
```
dante01yoon added a commit that referenced this pull request Sep 29, 2026
… checkout (1/3: discount rows) (#19276)

## Why

FE-3020 (Milestone 3, checkout guidebook 3, design source DES-1211,
DES-1020 and DES-1088). The full-page ledger drops the quote's
`discounts[]`, so a customer with an education discount or an applied
code sees a plan row and a total that do not add up. This is part 1 of
3: render the discounts the server already reports.

## Root cause

n/a, feature.

## How

- `buildSummaryLedger` now returns four discount slots next to each
family's rows:
  - `adjustments`: held discounts, rendered as rows before any Subtotal.
  - `promo`: the row for the customer's entered code.
- `subtotal`: the pre-discount base an entered code applied to. The
quote reports no such field, so no builder sets it; the row stays typed
but unrendered until the server reports one.
- `chips`: which code produced each discount, and whether it can be
removed. Part 3 renders these.
- `acceptsPromo`: only `charge_now` and `prorated_change` take a code.
The server refuses codes on scheduled changes
(`PROMOTION_CODE_INAPPLICABLE`), and `top_up` has no promo per DES-1088.
- Fold vs row is decided by `discount.kind`:
- `plan` means a catalog coupon the price is built from
(`annual_plan_discount_20`, `team_commitment_*`). It is already inside
the item amount and never becomes a row.
- `promotion` always becomes a row. The one whose `code` matches the
quote's `promotion_code` (case-insensitive) is the entered code; any
other is held.
- Row label is `name ?? "Promo code"`. The amount is
`−{amount_off_cents}`. The code string never appears in the label.
- Subtotal never renders today: the quote carries no pre-discount total,
and the amount due plus the entered code's `amount_off_cents` would be a
frontend guess at a server-owned number (every number on checkout is
server-reported). DES-1020's 50%-of-$6,048 framing needs a BE field
before Subtotal can show.
- `CheckoutLedger.vue` still renders a Subtotal row (muted, per Figma
351:14634) when `ledger.subtotal` is set, but no builder in this stack
ever sets it.

## Tradeoffs

- Figma draws discount amounts as `−$X` with no strikethrough. DES-1088
reserves strikethrough for discounts but the frames apply it only to the
yearly compare price. This PR follows the frames.
- "Mechanism coupon folds" uses the server's `kind: 'plan'`
classification instead of a catalog coupon id list, because the plans
catalog does not expose coupon ids.

## Blast Radius

Only `billing_web_checkout_ui = full_page`. A quote without
`discounts[]` renders exactly as before. Subtotal never renders in this
PR; see BE gaps.

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 381 tests pass.
- `summaryLedger.test.ts` has a table of 7 cases: a catalog coupon
folds; an unnamed entered code reads "Promo code"; a named code reads
its name; the code match ignores case; a held discount has a chip with
no remove; a held discount before an entered code still leaves Subtotal
out because the quote reports no pre-discount base; an entered code with
no amount gets no Subtotal.
- `CheckoutSummaryColumn.test.ts` covers the Subtotal row's presentation
contract given a ledger that already carries one, independent of any
builder.
- `CI=1 pnpm exec playwright test` in `apps/billing-web`: 41 passed.
`full-page-summary.spec.ts` covers a quote with a `plan` coupon, a held
Education discount and an entered code: `Education discount−$10.00`,
`Promo code−$20.00`, `Total due today$20.00`, never the folded coupon,
and never a `Subtotal` row.
- Mutation check: letting `plan` discounts through the filter fails 3
ledger cases.
- `pnpm knip`, lint, oxfmt and oxlint on changed files, and the pre-push
fallow audit: clean.

## BE gaps / design questions

- BE gap: no server-reported subtotal before discounts.
`SubscriptionPreview` has no `subtotal_cents` /
`amount_before_discount_cents` field, so Subtotal cannot render without
the frontend computing it from `amount_due_cents` plus the entered
code's `amount_off_cents`, which this fix removes as frontend-assembled
server state.
- BE gap: `SubscriptionDiscount` has no `duration`, `duration_in_months`
or `percent_off`. The sublines "first year" / "for N months" / "20% off"
cannot be rendered, so rows carry no subline.
- BE gap: a held discount's `code` may be an internal coupon id rather
than a customer-facing code. It is shown on the chip as the server sends
it.
- BE gap (BE-13100): no endpoint removes a standing coupon, so held
chips never get a remove control.
- Design: strikethrough on promo amounts (DES-1088 wording) versus none
(Figma frames).

## AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake
Stripe) at 1512x982 with `full_page` on. The quote is Pro monthly $50
with a held Education discount (-$10) and an entered code COMFY50
(-$20), the same scenario `full-page-summary.spec.ts` covers. AS IS is
the base branch
(#19267). The chips
render in part 3.

The TO BE screenshot below is recaptured from this fix: no Subtotal row,
because the quote does not report a pre-discount base and this PR no
longer computes one client-side.

| AS IS: the rows are missing, $50 resolves to $20 | TO BE: held row,
entered row, no Subtotal | Figma 351:14634 |
|---|---|---|
|
![as-is](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/b776082b48446e210b7b7dd9a4e054671ee67da6/as-is-held-and-entered.png)
|
![to-be](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/8a73391be26d5ad04c5585a8a8110a8b644e4169/to-be-held-and-entered.png)
|
![figma](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/b776082b48446e210b7b7dd9a4e054671ee67da6/figma-held-plus-code.png)
|

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| FE-3018 PR 2a |
#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
#19268 | mount
reconciliation, placeholders |
| FE-3018 PR 3b |
#19271 | bfcache and
cross-tab re-reconciliation |
| FE-3021 PR 1 |
#19279 | success,
already completed, in progress, received, unconfirmed |
| FE-3021 PR 2 |
#19280 | refusal, plan
not available, couldn't load |
| FE-3022 | #19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| FE-3019 PR 1 |
#19266 | summary
ledger model and builder |
| FE-3019 PR 2 |
#19267 | left-column
ledger rendering |
| **FE-3020 1/3** | **this PR** | **discount rows, fold rule, Subtotal**
|
| FE-3020 2/3 | #19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19276 stroke-width:3px
```
dante01yoon added a commit that referenced this pull request Sep 29, 2026
## Why

FE-3019 (Milestone 3, checkout guidebook 2, design source DES-1210 and
DES-1088). The full-page checkout's left column shows only "Subscribe to
{plan}", the plan's list price and the total, whatever the transition.
An upgrade reads as a subscribe, and nothing shows the credits, the
proration or the renewal. This PR renders the `SummaryLedger` from
#19266 in that column.

## Root cause

n/a, feature.

## How

- `FullPageCheckoutView.vue` builds the ledger from the capture quote
with `buildSummaryLedger`, the session's workspace name and the tier
copy. It replaces the old `summary` computed. This is the only wiring
change; `checkoutPage.ts`, `useFullPageCheckout.ts` and the payment
column are untouched.
- `components/fullPage/summary/CheckoutLedger.vue` renders the model in
this order:
  - eyebrow
  - headline with currency and optional rate
  - credits line with the coins icon
  - a divider that opens the ledger
  - items and adjustments, each with sublines
  - a divider and Subtotal, only when the model has one
  - a divider and "Total due today"
  - the trailing lines, with no divider after the Total
- `CheckoutSummaryColumn.vue` takes `ledger?: SummaryLedger` and keeps
PR 1's capture skeleton bars until the quote arrives. The section is now
the "Order summary" region, so tests and assistive tech can find it.
- The old `checkout.fullPage.eyebrow` and `eyebrowPlanOnly` keys are
removed.

## Tradeoffs

- Rows reuse existing tokens: `text-sm font-semibold` labels, `text-xs
text-muted-foreground` sublines, `border-border-default` dividers. No
new design tokens.
- The adjustments list renders like items and nothing fills it yet. The
promo row grammar and the strikethrough belong to FE-3020.
- Two `FullPageCheckoutView.test.ts` cases waited on "Subscribe to
Creator Plan" for an `upgrade` quote. They now wait on "Upgrade to
Creator Plan", which is the corrected eyebrow.

## Blast Radius

Only `billing_web_checkout_ui = full_page`. The embedded
`CheckoutView.vue` and `EmbeddedCheckout.vue` are untouched.

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 29 files, 374 tests
pass.
- `CheckoutSummaryColumn.test.ts`: the skeleton holds until the quote
arrives; the page-order outline of dividers and rows is divider, rows,
divider, Total, trailing lines; a Subtotal gets its own divider; a
scheduled headline carries its rate.
- `CI=1 pnpm exec playwright test` in `apps/billing-web` (fresh
production build): 40 passed.
- New `full-page-summary.spec.ts`: a new subscription reads "Subscribe
to Pro Plan · Personal", "$50 USD", "21,100 credits per month", the row,
the total and "Renews at $50.00 on July 28, 2026".
- A tier upgrade priced at a `proration_at` instant reads "Upgrade to
Pro Plan · Personal", "$32.50 USD", "6,858 credits added today (expire
July 28)", "Pro Plan - Prorated", "Existing credits are kept" and the
renewal.
- The quote is mocked through the cloud fixture's
`/billing/preview-subscribe`. `firebase_config` and `/api/features` are
untouched.
- `pnpm --filter @comfyorg/billing-web lint`, oxfmt and type-aware
oxlint on changed files, `pnpm knip`, and the pre-push `fallow:audit`:
clean.

## BE gaps / design questions

Carried from #19266:

- BE gap: no itemized proration amounts, so the upgrade shows one net
row, not Figma's $50.00 / -$17.50 pair.
- BE gap: the credits delta expiry is read from `renewal_at`.
- BE gap: no compare price for yearly plans.
- BE gap: credits are reported as credit-cents.
- BE gap: no top-up quote on billing-web.
- Team commit change proration is unverified (Wei, 2026-09-25), so
commit changes render neutral.
- Design: should Subtotal appear above Total with 2+ rows and no promo?
Figma says no; the DES-1088 wording says yes.

## AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake
Stripe) at 1512x982 with `full_page` on, workspace "Personal". The fake
Stripe mounts no real element, so the card area is empty. AS IS is the
base stack head
(#19264). Figma is the
DES-1210 frame for the same family (workspace "Comfy Studios", Figma's
own numbers).

| AS IS: an upgrade reads "Subscribe", the list price as headline, no
ledger | TO BE: prorated change | Figma 294:8378 |
|---|---|---|
| ![as-is
upgrade](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/as-is-tier-upgrade.png)
| ![to-be
upgrade](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/to-be-tier-upgrade.png)
| ![figma
upgrade](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/figma-tier-upgrade.png)
|

| AS IS: new subscription | TO BE: charge now, monthly | Figma 266:4370
|
|---|---|---|
| ![as-is new
sub](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/as-is-new-sub-monthly.png)
| ![to-be new
sub](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/to-be-new-sub-monthly.png)
| ![figma new
sub](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/figma-subscribe-monthly.png)
|

| AS IS: downgrade reads "Subscribe" and a $35.00 price over $0.00 | TO
BE: scheduled $0 | Figma 266:4420 |
|---|---|---|
| ![as-is
downgrade](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/as-is-downgrade-scheduled.png)
| ![to-be
downgrade](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/to-be-downgrade-scheduled.png)
| ![figma
downgrade](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/figma-downgrade-scheduled.png)
|

| TO BE: monthly to yearly, not prorated | TO BE: $0-due new
subscription (promo row pending FE-3020) | Figma 294:8224 |
|---|---|---|
| ![to-be monthly to
yearly](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/to-be-monthly-to-yearly.png)
| ![to-be zero
due](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/to-be-new-sub-zero-due.png)
| ![figma zero
due](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/766be797abafa4f2f0664fd9f80562b0a649d4ea/figma-zero-due.png)
|

Differences from Figma, all traced above: the upgrade shows one net row
because the quote has no itemized proration; yearly rows say "Billed
yearly" without the compare price; renewal and start dates carry the
year; the $0-due ledger lacks its promo row until FE-3020, so its row
and total do not reconcile on screen yet.

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| FE-3018 PR 2a |
#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
#19268 | mount
reconciliation, placeholders |
| FE-3018 PR 3b |
#19271 | bfcache and
cross-tab re-reconciliation |
| FE-3021 PR 1 |
#19279 | success,
already completed, in progress, received, unconfirmed |
| FE-3021 PR 2 |
#19280 | refusal, plan
not available, couldn't load |
| FE-3022 | #19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| FE-3019 PR 1 |
#19266 | summary
ledger model and builder |
| **FE-3019 PR 2** | **this PR** | **left-column ledger rendering** |
| FE-3020 1/3 | #19276
| discount rows, fold rule, Subtotal |
| FE-3020 2/3 | #19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19267 stroke-width:3px
```
dante01yoon added a commit that referenced this pull request Sep 29, 2026
…ckout (#19266)

## Why

FE-3019 (Milestone 3, checkout guidebook 2, design source DES-1210 and
DES-1088). The full-page checkout's left column shows only an eyebrow,
the plan's list price and the total. The guidebook's summary is a ledger
with one component, 8 slots and 4 families. This PR adds the data half:
a typed `SummaryLedger` model and a pure builder from the preview quote.
The next PR renders it.

## Root cause

n/a, feature.

## How

- `SummaryLedger` (`apps/billing-web/src/checkout/summaryLedger.ts`)
holds the family (`charge_now`, `prorated_change`, `scheduled`,
`top_up`), the eyebrow, the headline (amount, currency, optional rate),
the credits line (count and qualifier), `items` (at least one money
row), `adjustments` (the promo slot, empty until FE-3020), an optional
`subtotal`, the `total`, and `trailing` lines.
- Money rows and trailing lines are different types. A row has an
`amount`; a trailing line is a plain string. A future event such as
"Renews at..." cannot reach the dollar column, and it can only render
under the total.
- `buildSummaryLedger(quote, { workspace, tierName, t, locale })` picks
the family and fills the slots:
- Not immediate: `scheduled`. The headline is the future rate
(`renewal_amount_cents ?? cost_next_period_cents` plus "/ mo" or "/
yr"). Credits read "refill ... after {effective_at}". The trailing line
is "You'll keep {plan} until {effective_at}".
- An immediate `upgrade` the server priced at a `proration_at` instant,
unless it is TEAM to TEAM: `prorated_change`. The family is read from
the quote, never derived from plan durations. Credits read "N credits
added today (expire {renewal_at month and day})" from
`credits_today_cents`. The trailing lines are "Existing credits are
kept" and the renewal.
- Everything else: `charge_now`. A new subscription shows "N credits per
month/year" from `credits_next_period_cents`. A cadence switch shows
bare "N credits" only when `credits_today_cents` equals the allowance,
and otherwise "added today". Monthly to yearly adds "This month's
credits stay valid until {current_plan.period_end}". A $0-due new
subscription adds the BE-13104 line explaining why the card is
collected.
- The eyebrow is "{verb} {plan} · {workspace}". The workspace comes from
the session. Verbs are Subscribe to, Upgrade to, Switch to, and Change
to (team commit changes).
- `formatHeadlineMoney` drops `.00` and keeps real cents: $700, $32.50,
$0.
- Credits arrive as credit-cents. They are converted with the app-wide
`centsToCredits`, which adds `@comfyorg/shared-frontend-utils` to
billing-web.
- i18n keys live under `checkout.fullPage.summary`.

## Tradeoffs

- The builder returns translated strings, not message descriptors, so
the component stays a pure renderer and the tests read like the Figma
copy.
- The prorated signal is `transition_type === 'upgrade'` plus
`proration_at`, not `proration_at` alone. On main, billing-api stamps
`proration_at` on every Stripe transition preview, including the
monthly-to-yearly `reset_now` variant (served as `duration_change`,
charged in full) and scheduled ones. Only its `immediate` variant,
served as `upgrade`, is prorated. The legacy rail omits `proration_at`
and also types monthly-to-yearly prepay as `upgrade`, so an upgrade
without it reads as `charge_now`, never "Prorated".
- The "(expire {date})" wording follows the DES-1088 grammar rule. The
Figma frames still say "expires".
- The credits expiry reads month and day ("expire July 28"), as in
Figma; it always falls inside the current period. Every other date
carries the year ("July 28, 2026"). Figma drops it on some near dates,
and deciding which needs "today" inside a pure function.
- `top_up` exists only in the model. billing-web's checkout is
subscription-only today, so no builder produces it and no route reaches
it.

## Blast Radius

Nothing renders this yet. The next PR wires it into the
`billing_web_checkout_ui = full_page` view. No package code changes;
billing-web gains a workspace dependency on
`@comfyorg/shared-frontend-utils` (`creditsUtil` only).

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 28 files, 370 tests
pass.
- `summaryLedger.test.ts` compares whole ledgers in an `it.for` table:
new sub monthly, new sub yearly, $0-due, tier upgrade with
`proration_at` (prorated), tier upgrade without it (charge now), monthly
to yearly with `proration_at` (charge now), tier upgrade onto yearly,
downgrade scheduled, yearly to monthly scheduled, team commit change
with `proration_at` (neutral). The downgrade row also carries
`proration_at` and stays scheduled. It also covers the eyebrow without a
workspace and the headline cents table.
- Mutation checks, each turned a row red: dropping the `proration_at`,
`transition_type` or team commit condition from the prorated family,
dropping the `is_immediate` check, and removing the $0-due trailing
line.
- `pnpm --filter @comfyorg/billing-web lint`, oxfmt and type-aware
oxlint on changed files, `pnpm knip`, and the pre-push `fallow:audit`:
clean.

## BE gaps / design questions

- BE gap: the quote carries only the net `cost_today_cents` for a
proration. Figma's "Pro Plan - Prorated $50.00" and "Creator - Prorated
-$17.50" rows need both amounts from the server. Until then the prorated
family has one net row, no second money row and no Subtotal.
- BE gap: no explicit expiry for the prorated credits delta. It renders
from `renewal_at`, the period end the delta expires at per the verified
math.
- BE gap: no list or compare price for yearly plans, so "~~$35~~ $28 /mo
x 12" renders as "Billed yearly".
- BE gap: credits come as credit-cents; a server credits count would
retire the 211/USD conversion.
- BE gap: no top-up quote or top-up expiry field on billing-web.
- Team commit change proration is unverified (asked Wei 2026-09-25). A
TEAM to TEAM change renders neutral: "Change to Team Plan", the
allowance, no "Prorated" and no credits delta.
- Design: DES-1088 says Subtotal appears "when 2+ money rows precede a
promo or total", but Figma 294:8378 shows two rows before Total with no
Subtotal. This follows Figma: Subtotal only above an adjustment. Which
wins?

## AS IS / TO BE

No UI in this PR. The next PR carries the screenshots.

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

This PR now builds on
#19285 (the FE-3022
tip) instead of
#19264, so the ledger
lands after reconciliation, the ending screens and payment
authentication.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| FE-3018 PR 2a |
#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
#19268 | mount
reconciliation, placeholders |
| FE-3018 PR 3b |
#19271 | bfcache and
cross-tab re-reconciliation |
| FE-3021 PR 1 |
#19279 | success,
already completed, in progress, received, unconfirmed |
| FE-3021 PR 2 |
#19280 | refusal, plan
not available, couldn't load |
| FE-3022 | #19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| **FE-3019 PR 1** | **this PR** | **summary ledger model and builder**
|
| FE-3019 PR 2 |
#19267 | left-column
ledger rendering |
| FE-3020 1/3 | #19276
| discount rows, fold rule, Subtotal |
| FE-3020 2/3 | #19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19266 stroke-width:3px
```
dante01yoon added a commit that referenced this pull request Sep 29, 2026
…ll-page checkout (#19285)

## Why

FE-3022 (Milestone 3, checkout guidebook 5; design source DES-1213,
rulebook DES-1088). Between Pay and a terminal the full-page checkout
said nothing: a 3DS challenge, a charge in flight and a redirect method
all showed the same disabled Pay, a reload mid-challenge landed on a
"Finishing your payment…" placeholder, and a challenge the bank refused
left Pay busy forever because the subscribe promise never resolves for a
still-pending operation. This PR renders the two submit phases, the
redirect pre-money line, the lock, the re-openable challenge after a
reload and the Payment not verified card at capture. Stacked on
#19280.

## Root cause

n/a, feature.

## How

- `Attempt` becomes a union: `idle`, or `sent` carrying the operation
the lifecycle publishes for this Pay and the `redirectMethod` when the
chosen method pays on its own site. `submitPhaseOf(page)` derives the
submit area's phase from it and from a `waiting` page: `challenge`
(Phase A) only when the server says `authentication_state:
requires_action` (never from `action_url` presence, FE-2643),
`redirecting` for a non-card method, `processing` (Phase B) otherwise.
The swap is a state change; no timer exists.
- `CheckoutPayAction` renders the footnote in an always-mounted
`role="status" aria-live="polite"` node, so the Phase A line, the Phase
B line and the redirect line announce. Phase A adds a ghost Continue
verification (when `isChallengeReopenable`: hosted with `action_url`, or
an embedded challenge not already on screen) and a ghost Cancel payment
behind `canCancel`.
- `isLocked(page)` is true while a Pay is sent and on `waiting`: the
back arrow hides, the tabs and the saved-method list get `inert`,
`StripePaymentForm` gets a new `locked` prop that makes the elements
inert, and Pay is disabled with `aria-busy`. Only the phase buttons stay
live.
- The `waiting` placeholder column is replaced by the capture skeleton
with the phase footnote, so a reload during Phase A renders the verify
state and a return from a provider renders Phase B on the same layout.
The lifecycle's `continuationKey` watch re-drives the challenge from the
client secret the server still reports.
- A challenge the bank refuses leaves the operation pending with
`failed_retryable`; `followedOwn` lands that verdict as the Payment not
completed card (D1, one card for 3DS and redirect back-outs) with
`attempt` idle, and `isParked` treats it as capture's business so Pay is
live for the retry. `submitting` is now derived from the page, and a
subscribe promise resolving after a newer Pay is ignored
(`payGeneration`).
- `StripePaymentForm` emits the token's `payment_method_preview.type` as
a second `confirm` argument; the saved rail reads the method's `type`.
`PayChoice` carries `methodType`, and any non-card type is a redirect
method (the contract's own rule on `return_url`).
- The full page's `return_url` is the checkout URL itself
(`checkoutReturnUrl`), so the return from Alipay is a fresh mount riding
mount reconciliation; the M2 view keeps `/v1/result`.
- Design review (Alex 2026-09-28): D1 copy "Payment not completed / Your
payment wasn't completed, so you haven't been charged. Pay to try again,
or use a different payment method." (Figma 340-13834) replaces "Payment
not verified" in the refused-challenge path; the outcome kind is
`not_completed`. The back arrow stays hidden while a challenge is open
(the `locked` prop on the summary column).
- Copy: Phase A "Nothing has been charged yet.", Phase B "This payment
is already processing and can't be canceled.", redirect "Taking you to
{method} to finish paying. Nothing has been charged yet." with a
provider-less fallback; the method name comes from
`checkout.fullPage.phase.methods.*`.
- Rebased onto main: the dead `checkoutResultUrl` export is removed.

## Tradeoffs

- Cancel payment is hidden behind `PENDING_PAYMENT_CANCEL_AVAILABLE =
false` rather than faking a cancel: no endpoint cancels a pending
operation or PaymentIntent (the SDK's `cancel()` only changes a display
step), and a Cancel that returned to capture while the server kept the
challenge open would lie. The component and its tests support the
control; flipping the constant and wiring the click is the only work
left once the endpoint lands.
- The lock covers every in-flight phase, not only Phase A: the Figma
frames hide the back arrow on Phase B and the redirect frame too, and a
live tab switch under a charge in flight has no honest outcome.
- Continue verification renders for an embedded challenge only while its
status is `required`. The lifecycle re-drives a resumed challenge on its
own, so on a reload the button exists for the instant before Stripe's
modal opens; the hosted case (a customer who closed the invoice tab) is
where it does the work.
- The two `CheckoutPayAction` instances behind the tab row (the saved
panel's and the card form's, which stays mounted behind the Saved tab)
would be two live regions; only the visible one carries the phase.

## Blast Radius

`billing_web_checkout_ui = full_page` only for the page behaviour. Two
package changes reach the M2 views: `StripePaymentForm` gains an
optional `locked` prop and a second `confirm` argument (existing
listeners ignore it), and `checkoutResultUrl` is untouched.

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`, `pnpm --filter
@comfyorg/account-ui typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 31 files, 561 tests
pass (`@comfyorg/account-ui` stripe suite 26 pass). New: reducer tables
for `submitPhaseOf`, `isLocked`, `isChallengeReopenable`, `isParked`
with a refused challenge, and the transitions through a challenge;
`CheckoutPayAction` phases, live region, Cancel behind the capability,
Continue verification; view tests for Phase A to B to success with the
form locked, tabs inert, a refused challenge on its card with the same
form and a second subscribe, the Alipay line over a challenge, Continue
verification after a reload driving the challenge again, `return_url` on
`/v1/checkout`; the Stripe form's `locked` inert region and the emitted
method type.
- Mutation check: 15 mutations, each red (Phase A never detected 6, page
never locked 13, refused challenge stays waiting 4, own refused
challenge never lands the card 3, refused challenge not parked 2,
redirect line lost 2, Pay accepted while sent 3, reopen offered while
the modal is open 4, no live region 1, Cancel shown without the
capability 4, card treated as redirect 2, return URL stays on result 1,
submitting never clears 1, form ignores locked 1, method type not
emitted 1).
- `CI=1 pnpm exec playwright test` in `apps/billing-web`: 57 passed. New
`full-page-authentication.spec.ts`: Pay walks Phase A (locked, nothing
charged, Stripe driven with the poll's secret) into Phase B on the
bank's answer and then success; a saved-method Pay keeps the tabs inert;
a refused challenge lands on Payment not completed with the form still
mounted and Pay live; a reload during Phase A renders the verify state
and re-drives the challenge from the server's secret without a second
subscribe; a redirect method shows the pre-money line, never Phase B,
and leaves for the provider with `return_url` on `/v1/checkout`; the
return renders Phase B and follows to Already completed.
- `pnpm --filter @comfyorg/billing-web lint`, oxlint and oxfmt on
changed files, `pnpm knip`, pre-push `fallow:audit`: clean.

## BE gaps / design questions

- Phase-A cancel endpoint (BE): none exists for a pending operation or
PaymentIntent. Cancel payment stays hidden behind
`PENDING_PAYMENT_CANCEL_AVAILABLE`.
- D1 copy: the Payment not verified body keeps the DES-1088
third-variant copy ("Your bank didn't confirm this payment…"); the
genericised "Your payment wasn't completed, so you haven't been charged"
is pending design and is a locale-only change.
- The lifecycle auto-drives a resumed challenge on reload
(`usePaymentAttempt`'s continuation watch), for hosted pages as a
navigation. DES-1213 reads "re-openable"; if design wants the customer
to click first, that is an SDK change, not a page one.

## AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake
Stripe with the challenge held open) at 1512x982 with `full_page` on, by
a throwaway spec run once on the base of the stack (AS IS, PR 19280) and
once on this branch. Figma frames from file C1fxz3akrW7Pl22zM2b301. The
fake Stripe mounts nothing, so the element areas are empty in both
columns; the Figma frames show the elements as placeholders too. Known
differences from Figma: no Cancel payment (BE gap above), and the
Payment not verified copy is the DES-1088 third variant (D1).

| Screen | AS IS | TO BE | Figma |
|---|---|---|---|
| Phase A, challenge pending |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/asis-phase-a.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/tobe-phase-a.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/figma-phase-a-145-4584.png)
|
| Phase B, processing |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/asis-phase-b.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/tobe-phase-b.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/figma-phase-b-342-4767.png)
|
| Redirect pre-money line (Alipay) |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/asis-redirecting.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/tobe-redirecting.png)
| frame 447-6886 in
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/figma-happy-flow-312-10091.png)
|
| Verification failed at capture |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/asis-verification-failed.png)
(Pay stuck busy, no card) |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/tobe-verification-failed.png)
| last lane of
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/figma-failed-flow-314-10555.png)
|
| Reload during Phase A |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/asis-reload-phase-a.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/tobe-reload-phase-a.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/3729470ca331bff40a2e0f387c31a195f90d0123/figma-phase-a-145-4584.png)
|

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| FE-3018 PR 2a |
#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
#19268 | mount
reconciliation, placeholders |
| FE-3018 PR 3b |
#19271 | bfcache and
cross-tab re-reconciliation |
| FE-3021 PR 1 |
#19279 | success,
already completed, in progress, received, unconfirmed |
| FE-3021 PR 2 |
#19280 | refusal, plan
not available, couldn't load |
| **FE-3022** | **this PR** | **two-phase submit area, 3DS re-open,
redirect methods, verification failed** |
| FE-3019 PR 1 |
#19266 | summary
ledger model and builder |
| FE-3019 PR 2 |
#19267 | left-column
ledger rendering |
| FE-3020 1/3 | #19276
| discount rows, fold rule, Subtotal |
| FE-3020 2/3 | #19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19285 stroke-width:3px
```
dante01yoon added a commit that referenced this pull request Sep 29, 2026
…e screens (#19280)

## Why

FE-3021 PR 2 of 2 (design source DES-1212, Unauthorized and Checkout
Can't Load sections). PR 3a rendered a refusal and an outage as a bare
title and a line of copy. This PR renders the three designed full-page
refusals: Checkout not available (authorization), This plan is no longer
available (stale link) and Couldn't load your checkout (transient).
Stacked on #19279.

## Root cause

n/a, feature.

## How

- The page union gains `plan_unavailable`, and two events:
`planUnavailable` (only from `resolving`) and `retried` (only from
`unavailable`, back to `resolving`).
- `plan_unavailable` carries a reason: `retired` (a preview-subscribe
failure whose server code is `INVALID_PLAN`, code PLAN_NOT_FOUND),
`team_stop_missing` (the quote came back for a `TEAM` tier and the link
carried no `team_credit_stop_id`, code CHECKOUT_LINK_INVALID) or
`unreadable` (the link failed `parseBillingEntry`, code
CHECKOUT_LINK_INVALID). Any other quote failure is `unavailable`. The
stop stays encoded as `team_credit_stop_id` / `teamCreditStopId`.
- `endingOf` maps the three pages to `refused` (code = the capability
denial reason upper-cased, e.g. NOT_WORKSPACE_OWNER), `plan_unavailable`
and `load_failed` (code = the coded failure). `CheckoutEnding` gains the
refused tone and two primary actions.
- Checkout not available: billing-agnostic body, copyable reason code,
Contact support as the only action. Plan not available ("This plan isn't
available", the checkout's 404): View plans opens the cloud pricing
table (`checkout/cloudLinks.ts`, `/?pricing=1`, or `/?pricing=team` for
a team link missing its stop, with the billed workspace), Contact
support secondary. Couldn't load: Try again re-runs `reconcile()` and
the capture read in place, no navigation.
- Unreadable checkout links, full page only: `App.vue` no longer
explains a failed parse itself when the route is `/v1/checkout` (or the
sign-in page returning to it); `CheckoutRouteView` resolves the flag as
usual and renders `EntryErrorView` for `embedded` (M2 unchanged) or the
full page, whose composable starts on `plan_unavailable: unreadable`. A
signed-out visitor still signs in first, since the flag needs a session.
- Design review (Alex 2026-09-28): D5 (team link without a stop is an
invalid link), View plans into the pricing table on the Team tab, the
generic Plan not available copy, CHECKOUT_LINK_INVALID for unreadable
links. Screenshots below recaptured.
- The PR 3a inline refused/unavailable block and its locale keys are
removed.

## Tradeoffs

- Retrying can't help a dead slug, so Plan not available has no Try
again; a load failure can't be fixed by a catalog, so it has no View
plans. That is DES-1212's reason for two screens.
- Only `INVALID_PLAN` maps to Plan not available. The billing-api
preview answers an unknown slug 404 with no code body, and a
retired-but-present plan answers 422 `TRANSITION_NOT_ALLOWED`, which
also covers other refusals; both stay on Couldn't load.

## Blast Radius

Only `billing_web_checkout_ui = full_page`, and only the refused and
outage pages. The embedded views are untouched.

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 30 files, 507 tests
pass. New cases: reducer (`planUnavailable`, `retried`, and the pairs
that must do nothing), `endingOf` for all seven denial reasons,
`CheckoutEnding` copy, actions and emits for the three screens, view
tests for `INVALID_PLAN` vs any other refused quote and Try again after
a failed recovery (a second `recover` and preview, then capture).
- Mutation check on the whole stack, 17 mutations, each red; the four
specific to this PR: Try again ignored by the reducer, `INVALID_PLAN`
not recognised, Try again skipping the re-read, the refusal code not
upper-cased.
- `CI=1 pnpm exec playwright test` in `apps/billing-web`: 51 passed. New
in `full-page-endings.spec.ts`: a member refused with
`not_workspace_owner` sees the code and Contact support only; a 400
`INVALID_PLAN` quote renders PLAN_NOT_FOUND and View plans lands on the
cloud pricing table (`?pricing=1&workspace=ws_e2e`); a 503 quote renders
Couldn't load and Try again reaches an enabled Pay on the same URL with
exactly two quotes.
- After the design review: unit tables for the three reasons and their
codes (`endingScreen.test.ts`, reducer), a three-row view table
(retired, team plan without its stop, unreadable link: heading, code, no
form, no subscribe, View plans href), `CheckoutRouteView.test.ts`
(unreadable link is the entry error on `embedded` and the full page on
`full_page`), a router test that a signed-out visitor with an unreadable
checkout link reaches sign-in. E2E: a team link without its stop renders
CHECKOUT_LINK_INVALID and View plans lands on
`?pricing=team&workspace=ws_e2e`; an unknown-product checkout link
renders Plan not available on the full page and "We couldn't open that
billing page" with the flag off. 550 unit tests and the endings and
entry specs pass at this head.
- `pnpm --filter @comfyorg/billing-web lint`, oxfmt and oxlint on
changed files, `pnpm knip`, pre-push `fallow:audit`: clean.

## BE gaps / design questions

- `BillingFailure` carries no request id, so Couldn't load shows the
coded failure (REQUEST_FAILED) instead of the `req_…` reference in
Figma.
- Retired plans need a distinct server code; today only an unknown slug
is recognisable.
- The billing-web contract has no host catalog URL, so View plans goes
to `return_to` and is hidden without one.

## AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake
Stripe) at 1512x982 with `full_page` on, by a throwaway spec run once on
the base of the stack (AS IS, PR 3a placeholders) and once on this
branch. Figma frames from file C1fxz3akrW7Pl22zM2b301. Known difference
from Figma: the Couldn't load code is the coded failure, not a request
id (BE gap).

| Screen | AS IS | TO BE | Figma |
|---|---|---|---|
| Checkout not available |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/asis-refused.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/tobe-refused.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/figma-checkout-not-available-329-10947.png)
|
| Plan not available |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/asis-plan-not-available.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/04c6120c96b0488c1ee40b0aa7fb074229893c19/tobe-plan-not-available.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/figma-plan-not-available-433-6840.png)
|
| Plan not available, team link without its stop (CHECKOUT_LINK_INVALID)
| (no AS IS: rendered the form) |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/04c6120c96b0488c1ee40b0aa7fb074229893c19/tobe-plan-not-available-link-invalid.png)
| same frame |
| Couldn't load your checkout |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/asis-couldnt-load.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/tobe-couldnt-load.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/figma-couldnt-load-421-5804.png)
|

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| FE-3018 PR 2a |
#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
#19268 | mount
reconciliation, placeholders |
| FE-3018 PR 3b |
#19271 | bfcache and
cross-tab re-reconciliation |
| FE-3021 PR 1 |
#19279 | success,
already completed, in progress, received, unconfirmed |
| **FE-3021 PR 2** | **this PR** | **refusal, plan not available,
couldn't load** |
| FE-3022 | #19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| FE-3019 PR 1 |
#19266 | summary
ledger model and builder |
| FE-3019 PR 2 |
#19267 | left-column
ledger rendering |
| FE-3020 1/3 | #19276
| discount rows, fold rule, Subtotal |
| FE-3020 2/3 | #19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19280 stroke-width:3px
```
dante01yoon added a commit that referenced this pull request Sep 29, 2026
## Why

FE-3021 (Milestone 3, checkout guidebook 4, design source DES-1212 with
the DES-1088 rulebook). PR 3a rendered placeholders for every page that
is not capture. This PR replaces them with the designed ending screens
for money that settled or is still moving: Success, Already completed,
Payment in progress, Payment received and "We couldn't confirm your
payment". The refusal, Plan not available and Couldn't load screens
follow in the stacked PR 2 of 2.

Fixes FE-2856: an async capture (bank debit) sits in Stripe's processing
state for up to a day with no `action_url`, and no screen existed for
it. Arriving on checkout during that window now renders Payment in
progress instead of a fresh form or a spinner.

## Root cause

n/a, feature.

## How

- The page union gains `unconfirmed` (money whose outcome the page could
not learn) and replaces `terminal.started: boolean` with `attribution:
'started' | 'followed' | 'settled'`. Only `started` (this page's own
Pay) names a plan. `followed` is money watched settle from a screen that
promised to update; `settled` was already through on arrival or on a
re-read.
- `waitingOn(operation)` reads the op's own facts:
`authentication_state: succeeded` while still pending is Payment
received (charge through, plan landing); `processing` with `phase:
in_progress` and no `action_url` is Payment in progress; anything else
stays on PR 3a's verifying column for FE-3022.
- `reconciliation_needed` is never a card now. The BE maps both
`PaidUngrantable` and `SupersedeUncancelled` to it, so the client cannot
say whether money moved; it renders the hedged "We couldn't confirm"
screen. A verifying watch whose poll budget runs out lands there too; a
settling or received watch keeps its screen.
- When a watched operation's poll budget runs out, the page re-runs
`reconcile()`, which re-adopts the operation with a fresh budget. The
waiting screens promise to update on their own and a bank debit can take
hours. No new polling machinery.
- New pure selector `endingOf(page)` maps the page to an `EndingScreen`
and its support code; `CheckoutEnding.vue` renders it from one table
(tone, primary action, support link). Code card with a copy button
(`useClipboard`), Contact support mails the code, waiting screens carry
the close line and no Close button.
- Close: `window.close()` only when a script opened the tab, otherwise
`return_to` with `billing_result=success&billing_ref=<op>`, falling back
to the workspace's Plan & Credits settings when this family has no
destination for the target (the `returnLink` from PR 1). Close always
renders on the done family; the waiting family keeps its close line and
no button, as designed.
- Design review (Alex 2026-09-28): D4, Close destination rule from
DES-1212: `return_to`, else Plan & Credits. The `canClose` gate is gone.
- Removes `CheckoutTerminalCard.vue`.

## Tradeoffs

- The account-ui `CheckoutSuccess` (FE-3046) is not reused. It renders a
PrimeIcons icon billing-web does not load, needs a catalog
`CheckoutPlan` with a monthly credit count, and orders Close differently
from the full-page frame. The plan card here is built from the quote
only.
- The Success plan card omits the credits line from Figma: the quote
reports `credits_cents` (a dollar value) and billing-web keeps no
credits-per-dollar copy. FE-3019's ledger owns that conversion.
- The Success footer ("Auto closing and redirecting you back in 5...")
is not rendered: no countdown exists and DES-1212 says the footer never
promises a close it cannot perform.
- A pending op the lifecycle adopts from `/billing/status` is synthetic
until its first poll, so a revisit of a settled op passes through
verifying for one poll. Verifying resolving to success is therefore
Already completed; only Payment in progress, Payment received and
unconfirmed resolve to the card-less success.

## Blast Radius

Only `billing_web_checkout_ui = full_page`. The embedded views,
`payVerdict`'s card mapping for real declines, and the capture rails are
unchanged. `reconciliation_needed` on this page is now "We couldn't
confirm" instead of the processing-error card.

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 30 files, 483 tests
pass. New: `endingScreen.test.ts` (page to screen table),
`CheckoutEnding.test.ts` (copy, code card, Close/support per screen,
copy button, support mail), reducer tables for attribution, lapses,
`reconciliation_needed` and `waitingOn`, view tests for Close with and
without an opener, Payment in progress to received to success, and
lapsed watches re-reading.
- Mutation check, 13 mutations, each turned a test red: `waitingOn`
ignoring `action_url`, a settling lapse becoming unconfirmed, every
watched success attributed `followed`, own Pay ignoring
`reconciliation_needed`, unconfirmed dropping to capture while pending,
`reconciliation_needed` as a card again, lapsed watch not re-read, Close
always navigating, return link without outcome, settling screen hidden,
done family offering support, Close offered with nowhere to go, support
mail without the code.
- `CI=1 pnpm exec playwright test` in `apps/billing-web`: 48 passed. New
`full-page-endings.spec.ts`: success after Pay naming the plan, with
Close returning `billing_result=success&billing_ref=op_subscribe`;
Already completed on a revisit and again after reload, no subscribe;
FE-2856 processing capture renders Payment in progress, then resolves to
the card-less success when the op settles.
- `pnpm --filter @comfyorg/billing-web lint`, oxfmt and oxlint on
changed files, `pnpm knip`, pre-push `fallow:audit`: clean.
- After the design review: `FullPageCheckoutView.test.ts` adds Close
going to `/?settings=plan-credits&workspace=ws-team` for a
`platform_account` link the test family cannot resolve; the "Close
offered with nowhere to go" cases are removed with the gate. 519 unit
tests pass at this head. No e2e for the fallback: the router guard still
turns a checkout link with an unresolvable `return_to` into an entry
error before the page renders (kept so the flag-off embedded checkout is
unchanged), so on the full page the fallback is reachable only through
the unreadable-link route in the next PR, where View plans is the
action.

## BE gaps / design questions

- The op carries no plan, amount, workspace or credits-added facts, so
recovered ops stay card-less and the Payment received receipt rows
(DES-1088 situation 18) are not built. The receipt grammar and wave dots
wait on server-reported line facts.
- `reconciliation_needed` merges paid-ungrantable with
supersede-uncancelled; a distinct paid-ungrantable signal would let that
case render Payment received instead of the hedged screen.
- `authentication_state: processing` also covers
`requires_confirmation`, `requires_capture` and an unattempted intent,
so a seconds-scale confirmation can briefly render Payment in progress.
- No settled-op lookup: once the pending pointer is cleared a revisit
renders capture (the server still refuses a second Pay).
- Workspace in the body comes from the session credential, not the op.
- No Plan & Credits fallback URL exists without a valid `return_to`, so
Close is hidden there.

## AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake
Stripe) at 1512x982 with `full_page` on, by a throwaway spec run once on
the base branch (AS IS, PR 3a placeholders) and once on this branch.
Figma frames from file C1fxz3akrW7Pl22zM2b301. Known differences from
Figma: no credits line and no auto-close footer on Success (see
Tradeoffs), and recovered operations are card-less by the attribution
rule.

| Screen | AS IS | TO BE | Figma |
|---|---|---|---|
| Success, this page's Pay |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/asis-success.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/tobe-success.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/figma-success-subscription-77-4068.png)
|
| Already completed, revisit |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/asis-already-completed.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/tobe-already-completed.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/figma-already-completed-328-4444.png)
|
| Payment in progress (FE-2856) |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/asis-in-progress.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/tobe-in-progress.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/figma-payment-in-progress-372-4951.png)
|
| In progress settled while watched, card-less |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/asis-completed-after-watching.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/tobe-completed-after-watching.png)
| attribution rule, no frame |
| Payment received, plain |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/asis-received.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/tobe-received.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/figma-payment-received-plain-80-5456.png)
|
| We couldn't confirm (`reconciliation_needed`; AS IS offers Pay over
it) |
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/asis-unconfirmed.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/tobe-unconfirmed.png)
|
![](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/34865f04264b01ec8a52a6e189658ca3bb90271d/figma-couldnt-confirm-320-10760.png)
|

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| FE-3018 PR 2a |
#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
#19268 | mount
reconciliation, placeholders |
| FE-3018 PR 3b |
#19271 | bfcache and
cross-tab re-reconciliation |
| **FE-3021 PR 1** | **this PR** | **success, already completed, in
progress, received, unconfirmed** |
| FE-3021 PR 2 |
#19280 | refusal, plan
not available, couldn't load |
| FE-3022 | #19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| FE-3019 PR 1 |
#19266 | summary
ledger model and builder |
| FE-3019 PR 2 |
#19267 | left-column
ledger rendering |
| FE-3020 1/3 | #19276
| discount rows, fold rule, Subtotal |
| FE-3020 2/3 | #19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19279 stroke-width:3px
```
dante01yoon added a commit that referenced this pull request Sep 29, 2026
…ache restore and across tabs (#19271)

## Why

FE-3018 (Milestone 3, checkout guidebook 1). With PR 3a the full-page
checkout re-reads the live operation on mount, but two re-entries bypass
a mount: a page restored from the back-forward cache comes back exactly
as it was left, which after a Pay is a form over money that has since
moved (rule 16), and a sibling tab on the same checkout keeps its form
after another tab paid (rule 17). This PR re-runs reconciliation on
both, so the page flips to the truth rather than sitting on a stale
form. Second half of FE-3018 PR 3, stacked on
#19268.

## Root cause

n/a, feature.

## How

- `pageshow` with `event.persisted === true` calls `reconcile()`
(`useEventListener` from VueUse, in the view). A fresh navigation's
`pageshow` is ignored; the mount already reconciled.
- New `src/checkout/operationChannel.ts`: a channel named
`comfy:billing:op:${uid}:${workspaceId}`, BroadcastChannel where it
constructs, otherwise the `storage` event on a localStorage key of the
same name (each write is stamped so the event fires every time). Feature
detection follows account-core's `crossTabRefresh.ts`. A notice is `{
workspaceId, operationId, kind: 'started' | 'settled' }`; anything else,
and any notice for another workspace, is dropped. Neither transport
delivers to the tab that sent it.
- `useFullPageCheckout` opens one channel for the session's uid and
workspace, subscribes `() => reconcile()`, and closes it on scope
dispose. A notice is a nudge, never state: the listener reads nothing
from it and re-reads the server. Only an operation this page's own Pay
sent is announced (`started` when it first appears, `settled` when the
page lands on `terminal`), once each, so a tab that merely heard about
an operation never re-broadcasts it and two tabs cannot ping-pong.
- `reconcile()`'s generation guard from PR 3a is what makes re-running
it safe: a bfcache restore or a nudge overtaking a slower earlier read
wins, and the earlier answer is dropped.

## Tradeoffs

- Playwright's Chromium ships with the back-forward cache disabled, so
the e2e models the restore by dispatching `pageshow` with `persisted:
true` from the page, the event a real restore fires. The unit test does
the same.
- A plan the server activates with no operation to follow (`paySettled`)
has no operation id to announce, so sibling tabs learn of it only
through their own next read. They cannot double-charge either way: the
server refuses.
- The channel is same-origin script territory like the JWT refresh
channel; a forged notice costs a sibling one `/billing/status` read and
nothing more.

## Blast Radius

Only `billing_web_checkout_ui = full_page`. The embedded views are
untouched. No package code changes. The e2e fixture is unchanged.

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 28 files, 430 tests
pass.
- New `operationChannel.test.ts` (20): over a fake BroadcastChannel, a
sibling on the same uid and workspace hears a notice and the sender does
not; another uid or workspace hears nothing; another workspace's notice,
an unknown kind, a missing id, a string and null are dropped;
unsubscribe and close stop delivery. Over the storage event: each
publish writes a distinct stamped value under the scoped key; a value
another tab wrote is delivered; another key, a removal, unparseable text
and the malformed shapes are dropped; close stops delivery.
- `FullPageCheckoutView.test.ts` (+7): a persisted `pageshow` re-reads
and lands on waiting; a non-persisted one does nothing; the newest of
two overlapping reconciliations wins over a slower older one (no form
mounts); the channel is opened for `uid:workspace` and closed on
unmount; a sibling's nudge re-reads the server and renders what the
server says, not what the notice claimed; this page's own Pay announces
`started` then `settled` once each; an operation it only heard about is
never announced.
- Mutation check, ten mutations, each turned a test red: stale
reconciliation answer accepted, every pageshow re-reading, pageshow
never re-reading, sibling nudge ignored, heard-about operations
announced, settle never announced, channel not closed on unmount,
foreign-workspace notice delivered, malformed notice delivered, storage
notice not stamped.
- `CI=1 pnpm exec playwright test` in `apps/billing-web` (fresh
production build): 45 passed.
- New `full-page-cross-tab.spec.ts`: (ii) two pages in one context on
the same checkout, Pay in A, and B flips to waiting with no Pay and no
interaction, with more `/billing/status` reads than before the click and
exactly one `/billing/subscribe`; (iii) a page on capture whose server
state changes underneath it, then a synthetic persisted `pageshow`,
flips to waiting with no subscribe request.
- `pnpm --filter @comfyorg/billing-web lint`, oxfmt and oxlint on
changed files, `pnpm knip`, and the pre-push `fallow:audit`: clean.

## BE gaps

- Same as PR 3a: no settled-operation lookup, so a sibling that
reconciles after the operation has succeeded and the pointer was cleared
renders capture and sees the server's refusal. The nudge itself is fine;
the read it triggers has nothing to find.

## AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake
Stripe) at 1512x982 with `full_page` on. Two tabs in one browser context
on the same checkout. AS IS (PR 3a) is the left column staying put after
the other tab paid.

| AS IS: the sibling tab before the other tab's Pay (and, before this
PR, after it too) | TO BE: the sibling tab after the other tab's Pay,
with no interaction |
|---|---|
| ![sibling
before](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/61ef8851dd6e9b429aa03254bf0f380d72eb5b5b/sibling-before.png)
| ![sibling
after](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/61ef8851dd6e9b429aa03254bf0f380d72eb5b5b/sibling-after.png)
|

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| FE-3018 PR 2a |
#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
#19268 | mount
reconciliation, placeholders |
| **FE-3018 PR 3b** | **this PR** | **bfcache and cross-tab
re-reconciliation** |
| FE-3021 PR 1 |
#19279 | success,
already completed, in progress, received, unconfirmed |
| FE-3021 PR 2 |
#19280 | refusal, plan
not available, couldn't load |
| FE-3022 | #19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| FE-3019 PR 1 |
#19266 | summary
ledger model and builder |
| FE-3019 PR 2 |
#19267 | left-column
ledger rendering |
| FE-3020 1/3 | #19276
| discount rows, fold rule, Subtotal |
| FE-3020 2/3 | #19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19271 stroke-width:3px
```
…live operation (#19268)

## Why

FE-3018 (Milestone 3, checkout guidebook 1). The full-page checkout
rendered a fresh payment form on every mount, whatever the workspace was
already waiting on: a reload mid-3DS, a return from a provider page, a
customer coming back after re-auth, or a tab that lost the race to a
sibling all got a form over money in flight. A Pay that collided with
another operation locked Pay forever behind a skeleton. This PR makes
the page re-read the live operation on mount and after a collided Pay,
so one URL carries every re-entry (rules 2, 3, 4, 13, 18, 19). First
half of FE-3018 PR 3, stacked on
#19264.

## Root cause

n/a, feature.

## How

- `CheckoutPage` gains two kinds. `waiting { operation }` is money in
flight that this page did not send; `terminal { operation?, started }`
is a payment that went through, where `started` is whether this page's
own Pay sent it. `resolving` carries an optional `outcome` so a capture
it resolves into opens on the card of a recovered verdict. Capture gains
`attempt: 'idle' | 'sent'`, set by `paySubmitted` and cleared by every
Pay verdict, which is how an operation the lifecycle publishes mid-Pay
is known to be this page's own.
- New events, all pure:
- `reconciled { operation | undefined, outcome? }` is the lifecycle's
answer. Nothing pending releases a Pay held for a re-read and sends a
`waiting` page back to `resolving`. An operation goes through the same
transition as `operationChanged`.
- `operationChanged { operation, outcome? }` follows the operation the
lifecycle publishes. Success lands on `terminal` (attributed only while
`attempt === 'sent'`). In flight past card collection lands on
`waiting`, unless this page sent it, in which case the form stays with
Pay locked (Figma 312-10091 lane 1). Parked at `awaiting_payment_method`
is capture (rule 4, FE-2643: nothing is inferred from `action_url`). A
settled failure becomes the card above Pay, except for this page's own
Pay, whose verdict already knows about re-quotes. A page that was
`waiting` on an operation that parks or fails resolves a fresh capture,
since no form was ever mounted for it.
- `paySettled` covers a plan the server activated with no operation to
follow.
- `useFullPageCheckout`:
- On arrival `lifecycle.recover()` runs in parallel with the
capabilities, quote, saved methods and Stripe key reads. The capture
event is dispatched only after every reconciliation started before it
has answered, so capture never flashes before the server has spoken
(rule 3).
- `reconcile()` is generation-guarded: a run overtaken by a newer one
drops its answer, so re-running it converges (the bfcache and cross-tab
triggers land in PR 3b).
- A `waiting` page that drops back to `resolving` re-reads its capture
(quote, saved methods) rather than reusing state from before the
operation.
- `checkout.operation` is watched into `operationChanged`, with
`operationOutcomeOf` (extracted from `payVerdictOf`) supplying the
verdict. `timed_out` and `superseded` yield no card (rule 12).
- The backstop: `OPERATION_ALREADY_PENDING`, `CONFLICT` and `timed_out`
dispatch `payRejectedAsPending` and then `reconcile()`. The form stays
mounted with Pay locked until the re-read lands on `waiting`,
`terminal`, or frees Pay with typed details intact.
- A recovery the lifecycle refuses is an unknown, not "nothing pending":
in `resolving` it reads as the coded outage; elsewhere the page keeps
what it has.
- `canPay` no longer locks on any tracked operation, only on one in
flight, so a parked operation's Pay resubmits it (the lifecycle's
`resubmitTarget` path).
- `CheckoutWaitingColumn` is the payment column while waiting: a
`role="status"` polite line "Finishing your payment…", a body line, and
the capture skeleton bars. The summary column stays live. FE-3022
replaces it.
- `CheckoutTerminalCard` is the centred card: "You're all set" naming
the plan and workspace when this page sent the Pay, "Already completed"
naming the workspace and the operation reference when it did not
(attribution, rule 19). The workspace name comes from the session
credential. FE-3021 replaces it.
- The reducer is split into `reduceRail`, `reduceAttempt` and the
page-level switch behind two `Object.hasOwn` type guards, to stay under
the fallow cyclomatic gate.

## Tradeoffs

- A server-pending operation is adopted before its `phase` is known (the
status response carries only the id and continuation), so a parked
operation shows the waiting column for one poll round trip before it
resolves to capture. Treating an unknown phase as in flight is the safe
side: a form over money in flight is the failure this PR exists to
prevent.
- A recovery refusal outside `resolving` leaves the page as it was, so a
collided Pay whose re-read fails stays locked until the customer
reloads. A stuck lock beats a second charge.
- The auth-expiry path adds no UI: `App.vue` already sends a refused
session to `/sign-in?returnTo=`, and the remount reconciles. The e2e
proves it for both outcomes.

## Blast Radius

Only `billing_web_checkout_ui = full_page`. The embedded
`CheckoutView.vue`, `ResultView.vue` and `CheckoutPayment.vue` are
untouched. No package code changes. The fake billing client's `recover`
becomes a `Mock` so a test can script it.

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 27 files, 403 tests
pass.
- `checkoutPage.test.ts`: a 24-row reconciliation table (recovery
outcomes to page kind, parked to capture, waiting following its
operation to terminal / card / parked / vanished, attribution from this
page's Pay, terminal sticky against later re-reads), refused/unavailable
left alone, and `isParked`.
- `payVerdict.test.ts`: `operationOutcomeOf` table, including
`timed_out` and `superseded` yielding no card.
- `FullPageCheckoutView.test.ts`: skeleton held until reconciliation
answers with the quote already in hand (no form mounts); reload with
money in flight renders waiting with no form and follows it to Already
completed with the reference and no plan; invoice and in-progress phases
wait; parked renders capture with Pay live and Pay subscribes; a
recovered decline opens capture on its card with the operation id in the
support link; a settled payment lands on Already completed; a waited
operation that declines resolves a fresh capture on its card; a failed
recovery says so; the backstop for `OPERATION_ALREADY_PENDING` (waiting)
and `CONFLICT` (Already completed) with no decline, no support link,
`recover` called twice and the form mounted once; a collision that
re-reads as nothing frees Pay with the form still mounted; this page's
own success names the plan and workspace; a plan activated with no
operation lands on the terminal.
- Mutation check, each turned a test red (driver in the scratchpad, ten
mutations): capture rendered before reconciliation answers, parked
treated as in flight, success never attributed, collided Pay not
re-read, nothing pending not freeing a held Pay, waiting ignoring its
operation settling, form remounted during a re-read, recovery failure
read as nothing pending, and a recovered failure losing its card. The
stale-generation mutation survives here because nothing in 3a triggers
two overlapping reconciliations; PR 3b's pageshow test covers it.
- `CI=1 pnpm exec playwright test` in `apps/billing-web` (fresh
production build): 43 passed.
- New `full-page-reconciliation.spec.ts`: (i) reload with
`pending_billing_op_id` renders waiting with the eyebrow, no Pay, same
URL, then Already completed with the reference once the operation polls
as succeeded, no `/billing/subscribe`; parked `awaiting_payment_method`
renders capture and Pay resubmits; (iv) a Pay refused for an operation
the status starts reporting pending lands on waiting with no decline and
no subscribe request; a `409 CONFLICT` subscribe lands on Already
completed once the re-read finds the payment settled; auth expiry
mid-checkout (401 on the reads and the mint after Pay) goes to
`/sign-in?returnTo=<the same /v1/checkout URL>`, and Retry session comes
back to that URL reconciling into waiting (pending op) or capture (none)
with no charge.
- The PR 2 "collided Pay keeps Pay locked" spec is replaced by (iv),
since a pending operation on mount now lands on waiting rather than
capture.
- `pnpm --filter @comfyorg/billing-web lint`, oxfmt and oxlint on
changed files, `pnpm knip`, and the pre-push `fallow:audit`: clean.

## BE gaps

- No lookup for a settled operation. `/billing/status` names
`pending_billing_op_id` only while pending, and the tab-local pointer is
cleared on success, so a reload after a success finds nothing and
renders capture; the server's preview or subscribe refusal is then shown
as today. This PR deliberately does not compare `/billing/status`
`plan_slug` with the entry plan to fake "Already completed": that would
be frontend assembly of server state and mis-fires for a customer who
already had the plan.
- The status response carries no `phase` for the pending operation, so
the first render of a parked operation is the waiting column until `GET
/billing/ops/{id}` answers.
- The operation carries no plan, kind, amount or workspace
(`billingContracts.ts`), so a recovered terminal names the workspace
from the session credential and the plan only when this page sent the
Pay.

## AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake
Stripe) at 1512x982 with `full_page` on. AS IS is the base branch, where
every one of these mounts rendered the capture form (the first
screenshot in #19253
is that form).

| TO BE: reload while a payment is in flight (waiting, no form, summary
live) | TO BE: the operation settles, found on the server, unattributed
(reference, no plan) |
|---|---|
|
![waiting](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/61ef8851dd6e9b429aa03254bf0f380d72eb5b5b/to-be-waiting.png)
| ![already
completed](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/61ef8851dd6e9b429aa03254bf0f380d72eb5b5b/to-be-already-completed.png)
|

| TO BE: this page's own Pay goes through (plan and workspace named) |
|---|
|
![success](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/61ef8851dd6e9b429aa03254bf0f380d72eb5b5b/to-be-success.png)
|

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| FE-3018 PR 2a |
#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| **FE-3018 PR 3a** | **this PR** | **mount reconciliation,
placeholders** |
| FE-3018 PR 3b |
#19271 | bfcache and
cross-tab re-reconciliation |
| FE-3021 PR 1 |
#19279 | success,
already completed, in progress, received, unconfirmed |
| FE-3021 PR 2 |
#19280 | refusal, plan
not available, couldn't load |
| FE-3022 | #19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| FE-3019 PR 1 |
#19266 | summary
ledger model and builder |
| FE-3019 PR 2 |
#19267 | left-column
ledger rendering |
| FE-3020 1/3 | #19276
| discount rows, fold rule, Subtotal |
| FE-3020 2/3 | #19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19268 stroke-width:3px
```
@dante01yoon
dante01yoon merged commit 4932c78 into jaewon/fe-3018-saved-methods-rails Sep 29, 2026
35 of 36 checks passed
@dante01yoon
dante01yoon deleted the jaewon/fe-3018-rails-and-outcomes branch September 29, 2026 06:10
dante01yoon added a commit that referenced this pull request Sep 29, 2026
…s on the full-page checkout (#19263)

## Why

FE-3018 (Milestone 3, checkout guidebook 1). With
`billing_web_checkout_ui = full_page`, a customer with a card on file
still had to type a new one, and a failed saved-methods read or a failed
Stripe element either went unnoticed or took the whole payment column.
This PR adds the Saved / Add new payment tabs from Figma 187-8080 and
the in-place failure taxonomy from 360-4874, 368-15319 and 368-15401. It
is the first half of FE-3018 PR 2; the inline Pay outcomes follow in the
PR stacked on this one.

## Root cause

n/a, feature.

## How

- The `CheckoutPage` union from PR 0 grows instead of gaining a parallel
state. A new-subscription rail is now `{ element, saved, tab }`, with
`saved` one of `loading | ready | none | failed`. New events:
`savedLoaded(count)`, `savedFailed`, `savedRetried`, `tabSelected`.
- The rules live in `reduceCheckoutPage` and the pure `railView`:
- The first saved read picks the tab: Saved when the tab row shows at
all (methods on file, or the read failed), Add new otherwise.
- No event other than `tabSelected` changes the tab. A re-read that
finds nothing hides the tab row, which leaves Add new.
- Element failed with no saved methods, or with the saved read also
failed: the whole-column error (360-4874 / both rails down).
- Element failed beside saved methods: the error sits in the Add new tab
and Saved stays payable (368-15319).
- Saved read failed: the error sits on the Saved tab with its own copy,
and Add new stays live (368-15401).
- `useFullPageCheckout` reads the saved methods (`usePaymentMethods`) in
parallel with the capabilities, the quote and the Stripe key, so capture
never renders a half-known rail. Try again re-reads the list, remounts
the element, or both from the whole-column error.
- Pay on the Saved tab sends `saved_payment_method_id` (default method,
else the first, else the customer's pick).
`SubscribeRequest.saved_payment_method_id` is in the generated contract
and account-core already validates it; it was only unwired in
billing-web. A plan change still charges the method on file with no id,
matching `subscribeAcceptsSavedMethod` in the cloud app.
- The Stripe form stays mounted under `v-show` while the Saved tab is
open, so switching tabs never loses typed card details.
- `PaymentFormError` uses the shared notice style from the design
review: `bg-tertiary-background`, `rounded-lg p-4`, 8px gap, title
medium, every line 14/20.
- Design review (Alex 2026-09-28): notice card style applied to the
three rail-failure cards; screenshots below recaptured.
- Reuse: `CheckoutSavedMethods` (now exported from
`@comfyorg/account-ui/billing/checkout`, one line) for the single row
and the multi-method picker, and `usePaymentMethods`. New:
`PaymentMethodTabs`, `PaymentTabsRail`, `SavedMethodPanel`;
`PaymentFormError` takes a `rail` variant for the three copies.
- Rebased onto main: the account-ui `@source` styles commit is dropped
because main's `styles.css` already covers it.

## Tradeoffs

- The saved read joins the initial `Promise.all`, so capture waits for
max(quote, saved methods) rather than showing a tab row that could flip
under the customer. Both are fast reads; the alternative was an
auto-switch, which the rule set forbids.
- The Saved tab shows no billing address card (see BE gaps). The address
element is part of the Stripe form, so it is visible only on Add new.
- In the tabbed layout the Stripe form keeps its "Choose how you would
like to pay." subtitle under the tab row; its "Payment method" heading
is blanked so the label is not doubled.
- `CheckoutSavedMethods` is reused as-is, so the single-method row keeps
its "Change" link (it selects Add new) and a "Saved payment method"
label that Figma does not draw.

## Blast Radius

Only `billing_web_checkout_ui = full_page`, which Cloud serves per
account (cloud PR 10904, merged). `CheckoutView.vue` (embedded M2) is
untouched; `buildSubscribeRequest` gained an optional
`savedPaymentMethodId` that the embedded view never passes. account-ui
gains one export. The new `@source` adds CSS rules only for class names
that appear in the account-ui checkout components; an embedded-view
element using one of those names would pick up its intended style. The
full e2e suite, including the embedded checkout specs, passes.

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 26 files, 312 tests
pass. `checkoutPage.test.ts` tables every event sequence, every ignored
transition, and a no-auto-switch table over (tab x element/saved event);
`railView` has one row per taxonomy frame.
`FullPageCheckoutView.test.ts` adds 6 component cases (default method
charged without a token, single row vs picker, form mounted once across
tab switches, 368-15401 retry, 368-15319, both rails down).
- Mutation check, each turned a test red: allowing a Saved tab with
nothing saved, auto-switching on element or saved failure, landing a
failed first read on Add new, dropping or widening the whole-column
rule, letting Pay on Saved ignore the list, not sending the saved id,
`v-if` instead of `v-show` on the Stripe form, and a column retry that
skips the saved read.
- `CI=1 pnpm exec playwright test` in `apps/billing-web` (fresh
production build): 36 passed on this branch.
`full-page-checkout.spec.ts` covers the saved-method subscribe body,
360-4874, 368-15319 (fake Stripe `loaderror` with a card on file) and
368-15401 (`GET /billing/payment-methods` 500, then Try again).
`checkout-ui.spec.ts` still covers flag off and fallback.
- `pnpm --filter @comfyorg/billing-web lint`, oxfmt and oxlint on
changed files, `pnpm knip`, and the pre-push `fallow:audit`: clean.

## BE gaps / design questions

- BE gap: `SavedPaymentMethod` carries no billing address
(`types.gen.ts` `SavedPaymentMethod` is `{ id, type, is_default, brand?,
last4? }`), so the Figma "John Doe / 000 Name St." card with its
"Update" action is not rendered. Nothing is fabricated.
- Design: the 368-15319 body copy ("…or pay with a saved payment
method.") is taken from Figma; DES-1088 quotes only the 360 copy.
- Design: brands render as the API sends them (`visa •••• 4242`), the
existing shared component's behavior.

## AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake
Stripe) at 1512x982 with `full_page` on. The fake Stripe mounts no real
element, so the card and address areas are empty. AS IS is the base
branch (PR 1).

| AS IS: a card on file, PR 1 shows only the card form | TO BE: Saved
tab, picker for two methods (187-8080) |
|---|---|
| ![as-is card on
file](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/953336921094b4405b411f4b358e27f257eed54a/as-is-card-on-file.png)
| ![saved
tabs](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/953336921094b4405b411f4b358e27f257eed54a/to-be-saved-tabs.png)
|

| TO BE: Add new payment tab | TO BE: element failed, no saved method
(360-4874) |
|---|---|
| ![add new
tab](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/953336921094b4405b411f4b358e27f257eed54a/to-be-add-new-tab.png)
|
![360](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/66b180feaf5f6af7666a58374ecfca368c478cce/to-be-360-element-failed.png)
|

| TO BE: element failed beside saved methods (368-15319) | TO BE:
saved-methods read failed (368-15401) |
|---|---|
|
![368-15319](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/66b180feaf5f6af7666a58374ecfca368c478cce/to-be-368-15319-element-failed-saved.png)
|
![368-15401](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/66b180feaf5f6af7666a58374ecfca368c478cce/to-be-368-15401-saved-failed.png)
|

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | #19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
#19252 | page state
union and pure transition |
| FE-3018 PR 1 |
#19253 | shell,
eyebrow, capture skeleton |
| **FE-3018 PR 2a** | **this PR** | **saved-method tabs, rail failure
taxonomy** |
| FE-3018 PR 2b |
#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
#19268 | mount
reconciliation, placeholders |
| FE-3018 PR 3b |
#19271 | bfcache and
cross-tab re-reconciliation |
| FE-3021 PR 1 |
#19279 | success,
already completed, in progress, received, unconfirmed |
| FE-3021 PR 2 |
#19280 | refusal, plan
not available, couldn't load |
| FE-3022 | #19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| FE-3019 PR 1 |
#19266 | summary
ledger model and builder |
| FE-3019 PR 2 |
#19267 | left-column
ledger rendering |
| FE-3020 1/3 | #19276
| discount rows, fold rule, Subtotal |
| FE-3020 2/3 | #19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | #19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19263 stroke-width:3px
```
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 29, 2026
…lestone 3 full-page checkout behind billing_web_checkout_ui (Comfy-Org#19253)

> **Now carries the whole Milestone 3 full-page checkout.** The approved
stacked PRs above were squash-merged top-down into this branch; each was
reviewed and approved at its own head:
Comfy-Org#19263 (saved methods,
rail failures), Comfy-Org#19264
(inline outcomes, keep-subscription consent, re-quote failure),
Comfy-Org#19268 (mount
reconciliation),
Comfy-Org#19271 (bfcache,
cross-tab), Comfy-Org#19279
(ending screens),
Comfy-Org#19280 (refusal, plan
not available, couldn't load),
Comfy-Org#19285 (3DS / redirect
two-phase submit),
Comfy-Org#19266 +
Comfy-Org#19267 (summary
ledger), Comfy-Org#19276 +
Comfy-Org#19277 +
Comfy-Org#19278 (promo codes).
Everything stays behind `billing_web_checkout_ui = full_page`; flag off
is the Milestone 2 checkout unchanged. Design review: Alex Tov confirmed
the PRs match the guidebooks (#proj-billing, 2026-09-28).

## Why

FE-3018 (Milestone 3, checkout guidebook 1: flow and entry). With
`billing_web_checkout_ui = full_page`, `/v1/checkout` rendered an empty
"Checkout" stub. This PR turns it into the two-tone full-page capture
from Figma 187-8080, with the loading rule from 479-4848 (DES-1014) and
the element-failure column from 360-4874.

## Root cause

n/a, feature.

## How

- `useFullPageCheckout` reads capabilities, the quote and the Stripe key
in parallel on arrival and dispatches one event into the `CheckoutPage`
reducer from the PR below: a denied `can_subscribe_self_serve` goes to
`refused`, a failed read goes to `unavailable`, a quote goes to
`capture`. Nothing renders capture before all three are in; the key is
awaited because `StripePaymentForm` reads it only on mount.
- Skeleton: the header, the "Total due today" label, both payment group
labels, the Pay button and the terms line render for real; eyebrow,
headline and total are skeleton bars. No spinner.
- Pay enables only when the quote has arrived and the Stripe payment
element reports `payment_element_ready` (the address element's ready
does not count). A started operation keeps Pay locked so a second click
cannot charge twice; rendering the post-Pay outcome is PR 2 / PR 3.
- Eyebrow is `Subscribe to {tier} Plan · {workspace.name}`, with the
name read from the minted session credential, not the quote.
- The back arrow goes to the entry's allowlisted `return_to` through
`buildReturnUrl`, the same helper the embedded view uses. When this
family has no destination for the target, it falls back to the
workspace's Plan & Credits settings on the cloud origin
(`checkout/cloudLinks.ts`, `/?settings=plan-credits&workspace=<id>`, the
same deep link the contract's `comfyui_credits` target names), so the
arrow always renders and always has somewhere to go.
- Design review (Alex 2026-09-28): D4. Back arrow destination is
`return_to` with the Plan & Credits fallback; the `canGoBack` prop is
gone since there is always a destination.
- A `payment_element_failed` replaces the whole payment column with the
360-4874 card and a Try again that remounts `StripePaymentForm` and
re-disables Pay until the new element is ready.
- A plan change (`transition_type` other than `new_subscription`)
renders Pay without a card form and subscribes without a confirmation
token, as the embedded view does.
- Subscribe goes through `useCheckout().subscribe` with the same request
fields as the embedded view (quote id and version, proration, credit
stop, `return_url` to `/v1/result`).
- Reuse: `StripePaymentForm`, `usePreviewSubscribe`, `useCheckout`,
`formatQuoteMoney`, and `CheckoutTermsNote` (now exported from
`@comfyorg/account-ui/billing/checkout`, one line).
- The refusal is a minimal placeholder with i18n copy; FE-3021 owns the
real ending screen.
- Rebased onto main: the `CheckoutView.vue` refactor is dropped because
Comfy-Org#19101 owns the M2 `CheckoutView`, the seven `checkout.*` locale keys
the full page reads are restored, and `subscribeRequest.ts` serves the
full page only.

## Tradeoffs

- The subscribe-request builder and `resultUrl` are a copy of the
embedded view's, because that view must stay untouched while the flag is
off. The copy goes when the embedded variant is retired.
- The left column is eyebrow, headline and total only; the ledger
grammar, credits line and promo chip are FE-3019 / FE-3020.
- The refusal copy is one generic line; the reason stays in the state
for FE-3021.
- `h-84` placeholder boxes stand in for the Stripe elements until the
quote arrives, because `StripePaymentForm` never mounts its elements
when the amount is not yet known.
- Known gaps, all parity with the embedded view and all for PR 2 (listed
so nobody serves `full_page` before then): after Pay the page shows no
outcome and keeps Pay locked; a quote needing reactivation confirmation
gets the server's coded refusal on Pay instead of the confirm checkbox;
a zero-amount quote, an `allowed: false` quote, or one without a payment
method configuration leaves Pay disabled with no explanation.
- The page is split into `CheckoutSummaryColumn` and
`CheckoutPaymentColumn` so the view template stays under the fallow
complexity gate.

## Blast Radius

Only `billing_web_checkout_ui = full_page`, which Cloud does not serve
yet (cloud PR 10904, merged); targeted per account in PostHog. Flag off
is byte-identical: `CheckoutView.vue`, `CheckoutPayment.vue`,
`EmbeddedCheckout.vue` are untouched and the embedded e2e still passes.
The e2e fake Stripe now fires element `ready`, which the embedded view
ignores.

## Verification

- `pnpm --filter @comfyorg/billing-web typecheck`: clean.
- `pnpm --filter @comfyorg/billing-web test:unit`: 25 files, 266 tests
pass (13 new component cases in `FullPageCheckoutView.test.ts`; mutating
the operation lock, the `canPay` guard in `pay()`, or the `allowed`
check each turns one red).
- `pnpm exec playwright test` in `apps/billing-web` (fresh production
build, `CI=1`): 33 passed. New `e2e/full-page-checkout.spec.ts` asserts
the eyebrow names plan and workspace, Pay is labelled "Pay and
subscribe" and enabled once ready, and the failed-element column plus
Try again. `checkout-ui.spec.ts` still asserts flag-off shows "Confirm
your payment".
- `pnpm --filter @comfyorg/billing-web lint` (eslint + stylelint), oxfmt
and oxlint on changed files, `pnpm knip`: clean.
- After the design review: `cloudLinks.test.ts` (the settings deep link
with and without a workspace) and a two-row table in
`FullPageCheckoutView.test.ts` (Back to `comfyui_workspace`, Back to
Plan & Credits for `platform_account`, which the test family cannot
resolve). Typecheck and 294 unit tests pass at this head.

## Design questions

- 360-4874 drops the back arrow in the whole-column failure; the 368
frames keep it. This PR keeps it, since the summary column stays live
and the customer still needs a way back. Intentional in Figma, or a
frame slip?
- The error card background in Figma is `#2d2e32`
(`semantic/secondary/background-hover`), which has no repo token. This
uses `bg-secondary-background-hover` (`#313235` in dark). Retoken, or
accept?

## AS IS / TO BE

Captured from the e2e harness (production build, mocked Cloud, fake
Stripe) at 1512x982, `full_page` on. The fake Stripe mounts no real
element, so the ready state shows the element area empty.

| AS IS (base: empty stub) | TO BE: capture skeleton (479-4848) |
|---|---|
|
![as-is](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/47c1ef8e2f8a7afa903c2a3152cfab3a896d217c/as-is-full-page.png)
|
![skeleton](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/47c1ef8e2f8a7afa903c2a3152cfab3a896d217c/to-be-skeleton.png)
|

| TO BE: capture ready, Pay enabled | TO BE: element failed, whole
column (360-4874) |
|---|---|
|
![ready](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/47c1ef8e2f8a7afa903c2a3152cfab3a896d217c/to-be-ready.png)
|
![element-failed](https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/47c1ef8e2f8a7afa903c2a3152cfab3a896d217c/to-be-element-failed.png)
|

## Where this sits in the plan

One linear stack on `main`: each PR is based on the one above it in the
table. The former FE-3019/FE-3020 sibling stack now sits on top of
FE-3022.

| Step | PR | Scope |
|---|---|---|
| FE-3067 | Comfy-Org#19248
(merged) | flag and variant switch |
| FE-3018 PR 0 |
Comfy-Org#19252 | page state
union and pure transition |
| **FE-3018 PR 1** | **this PR** | **shell, eyebrow, capture skeleton**
|
| FE-3018 PR 2a |
Comfy-Org#19263 | saved-method
tabs, rail failure taxonomy |
| FE-3018 PR 2b |
Comfy-Org#19264 | inline Pay
outcomes, backstop, reactivation |
| FE-3018 PR 3a |
Comfy-Org#19268 | mount
reconciliation, placeholders |
| FE-3018 PR 3b |
Comfy-Org#19271 | bfcache and
cross-tab re-reconciliation |
| FE-3021 PR 1 |
Comfy-Org#19279 | success,
already completed, in progress, received, unconfirmed |
| FE-3021 PR 2 |
Comfy-Org#19280 | refusal, plan
not available, couldn't load |
| FE-3022 | Comfy-Org#19285 |
two-phase submit area, 3DS re-open, redirect methods, verification
failed |
| FE-3019 PR 1 |
Comfy-Org#19266 | summary
ledger model and builder |
| FE-3019 PR 2 |
Comfy-Org#19267 | left-column
ledger rendering |
| FE-3020 1/3 | Comfy-Org#19276
| discount rows, fold rule, Subtotal |
| FE-3020 2/3 | Comfy-Org#19277
| promo entry state, Pay binding, URL promo |
| FE-3020 3/3 | Comfy-Org#19278
| promo entry UI, chips, expired card |

```mermaid
graph LR
  M["main (19248 merged)"] --> N19252["19252 page state"] --> N19253["19253 shell"] --> N19263["19263 rails"] --> N19264["19264 outcomes"] --> N19268["19268 mount reconciliation"] --> N19271["19271 bfcache and cross-tab"] --> N19279["19279 money endings"] --> N19280["19280 refusal screens"] --> N19285["19285 payment authentication"] --> N19266["19266 ledger model"] --> N19267["19267 ledger UI"] --> N19276["19276 discount rows"] --> N19277["19277 promo entry state"] --> N19278["19278 promo entry UI"]
  style N19253 stroke-width:3px
```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cloud/1.55 Backport PRs for cloud 1.55 core/1.55 Backport PRs for core 1.55 needs-backport Fix/change that needs to be cherry-picked to the current feature freeze branch risk:xhigh PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants